API Retrieve - Recuperación de base de conocimientos - Alibaba Cloud Model Studio

Recupera fragmentos de texto relevantes de una base de conocimientos mediante búsqueda vectorial y por palabras clave.

Descripción de la operación

Cómo llamar: Utilice la versión más reciente del SDK de Alibaba Cloud Model Studio para llamar a esta API. El SDK gestiona el cálculo de firmas automáticamente.
Permisos requeridos:
- Usuario RAM (subcuenta): Un usuario RAM debe tener permisos de API para Model Studio y unirse a un espacio de trabajo. La política AliyunBailianDataFullAccess incluye el permiso sfm:Retrieve requerido.
- Cuenta de Alibaba Cloud (cuenta principal): Esta cuenta tiene los permisos necesarios de forma predeterminada y puede llamar a la API directamente.
Latencia de respuesta: Las operaciones de recuperación pueden tener tiempos de respuesta más largos. Configure tiempos de espera y estrategias de reintento adecuados.
Idempotencia: Esta API es idempotente.

Probar ahora

Pruebe esta API en OpenAPI Explorer; no es necesaria la firma manual. Las llamadas exitosas generan automáticamente código SDK que coincide con sus parámetros. Descárguelo con seguridad de credenciales integrada para uso local.

Prueba

Autorización de RAM

La siguiente tabla describe la autorización necesaria para llamar a esta API. Puede definirla en una política de Resource Access Management (RAM). Las columnas de la tabla se detallan a continuación:

Action: Las acciones se pueden utilizar en el elemento Action de las declaraciones de políticas de permisos de RAM para otorgar permisos para realizar la operación.
API: La API que puede llamar para realizar la acción.
Nivel de acceso: El nivel de acceso predefinido otorgado para cada API. Valores válidos: create, list, get, update y delete.
Tipo de recurso: El tipo de recurso que admite la autorización para realizar la acción. Indica si la acción admite permisos a nivel de recurso. El recurso especificado debe ser compatible con la acción. De lo contrario, la política será ineficaz.
- Para las API con permisos a nivel de recurso, los tipos de recursos requeridos están marcados con un asterisco (*). Especifique el Nombre de recurso de Alibaba Cloud (ARN) correspondiente en el elemento Resource de la política.
- Para las API sin permisos a nivel de recurso, se muestra como Todos los recursos. Utilice un asterisco (*) en el elemento Resource de la política.
Clave de condición: Las claves de condición definidas por el servicio. La clave permite un control granular, aplicándose ya sea solo a acciones o a acciones asociadas con recursos específicos. Además de las claves de condición específicas del servicio, Alibaba Cloud proporciona un conjunto de claves de condición comunes aplicables a todos los servicios compatibles con RAM.
Acción dependiente: Las acciones dependientes necesarias para ejecutar la acción. Para completar la acción, el usuario de RAM o el rol de RAM debe tener los permisos para realizar todas las acciones dependientes.

Acción	Nivel de acceso	Tipo de recurso	Clave de condición	Acción dependiente
sfm:Retrieve	none	Todos los recursos ``	None	None

Acción

Nivel de acceso

Tipo de recurso

Clave de condición

Acción dependiente

sfm:Retrieve

none

*Todos los recursos

*

None

Sintaxis de la solicitud

POST /{WorkspaceId}/index/retrieve HTTP/1.1

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Descripción	Ejemplo
WorkspaceId	string	Sí	El ID del espacio de trabajo. Cómo usar espacios de trabajo.	llm-3shx2gu255oqxxxx

Parámetros de solicitud

Parámetro	Tipo	Obligatorio	Descripción	Ejemplo
Query	string	No	La consulta de entrada (prompt original del usuario). Sin límite de longitud.	Introducción a la plataforma Alibaba Cloud Model Studio
DenseSimilarityTopK	integer	No	Número de fragmentos de texto que se recuperarán mediante búsqueda vectorial. Valores válidos: de 0 a 100. La suma de `DenseSimilarityTopK` y `SparseSimilarityTopK` no debe exceder 200. Valor predeterminado: 100.	100
EnableReranking	boolean	No	Habilita la reclasificación (Base de conocimientos). Valores válidos: `true`: Habilita la reclasificación. `false`: Deshabilita la reclasificación. Valor predeterminado: `true`. Valores válidos: true : Enabled false : Deshabilitado	true
EnableRewrite	boolean	No	Habilita la reescritura conversacional de consultas. Valores válidos: `true`: Habilita la reescritura de consultas conversacionales. `false`: Deshabilita la reescritura de consultas conversacionales. Valor predeterminado: `false`. Valores válidos: true : Enabled false : Deshabilitado	false
Rerank	array<object>	No	Las configuraciones de reclasificación.
	object	No	Un objeto que contiene configuraciones de reclasificación.
ModelName	string	No	El modelo de reclasificación. Anula el modelo predeterminado configurado para la base de conocimientos. Valores válidos: `gte-rerank-hybrid`: Realiza la reclasificación mediante el modelo gte-rerank (híbrido). `gte-rerank`: Realiza la reclasificación utilizando el modelo gte-rerank. Predeterminado: el modelo configurado para la base de conocimientos. Utilice `gte-rerank` únicamente para clasificación semántica. Recomendamos `gte-rerank-hybrid` si requiere tanto clasificación semántica como funciones de coincidencia de texto para obtener una mayor relevancia. Valores válidos: gte-rerank-hybrid : Realiza la reclasificación utilizando el modelo gte-rerank (híbrido). gte-rerank : Realiza la reclasificación utilizando el modelo gte-rerank.	gte-rerank-hybrid
RerankMode	string	No	Este parámetro aún no está disponible. No especifique un valor para él. Valores válidos: similar : `similar`: Modo de similitud. custom : `custom`: Modo personalizado. qa : `qa`: (Predeterminado) Modo de preguntas y respuestas.	qa
RerankInstruct	string	No	Este parámetro aún no está disponible. No especifique un valor para él.
RerankMinScore	number	No	Puntuación mínima de similitud para los resultados de reclasificación. Valores válidos: de 0.01 a 1.00. Anula el umbral configurado para la base de conocimientos. Predeterminado: el umbral configurado para la base de conocimientos.	0.20
RerankTopN	integer	No	Número de fragmentos de texto mejor clasificados que se devolverán tras la reclasificación. Valores válidos: de 1 a 20. Valor predeterminado: 5.	5
Rewrite	array<object>	No	Configuración para la reescritura de consultas conversacionales.
	object	No	Un objeto que contiene configuraciones para la reescritura de consultas conversacionales.
ModelName	string	No	El modelo para la reescritura conversacional de consultas. Reescribe la consulta basándose en el contexto de la conversación para mejorar la recuperación. Valor válido: `conv-rewrite-qwen-1.8b`: El único modelo compatible actualmente con esta función. Predeterminado: `conv-rewrite-qwen-1.8b`. Valores válidos: conv-rewrite-qwen-1.8b : El modelo conv-rewrite-qwen-1.8b	conv-rewrite-qwen-1.8b
SparseSimilarityTopK	integer	No	Número de fragmentos de texto que se recuperarán mediante coincidencia de palabras clave. Valores válidos: de 0 a 100. La suma de `DenseSimilarityTopK` y `SparseSimilarityTopK` no debe exceder 200. Valor predeterminado: 100.	100
IndexId	string	Sí	El ID de la base de conocimientos, devuelto como `Data.Id` por `CreateIndex`. Asegúrese de que la base de conocimientos especificada exista y no haya sido eliminada.	5pwe0mxxxx
SaveRetrieverHistory	boolean	No	Guarda el historial de recuperación para pruebas. Valores válidos: `true`: Guarda el historial de recuperación. `false`: No guarda el historial de recuperación. Valor predeterminado: `false`.	false
SearchFilters	array<object>	No	Condiciones de recuperación personalizadas (como etiquetas) para filtrar resultados. Se aplica solo cuando `is_displayed_chunk_content` es `true`. SearchFilters para una base de conocimientos.
	object	No	Un objeto de condición de búsqueda.
	string	No
Images	array	No	Las URL de las imágenes para incluir en la consulta.
	string	No	Para bases de conocimientos de preguntas y respuestas basadas en imágenes, proporcione URL de imágenes. El sistema vectoriza la imagen de entrada para la recuperación si existe un índice de imágenes. De lo contrario, la imagen de entrada se ignora. Este campo no es compatible con bases de conocimientos de tipo búsqueda de documentos o consulta de datos. Si se especifica, este campo no tendrá efecto. Make sure that the link is publicly accessible and points to a valid image file. Example: https://example.com/downloads/pic.jpg	https://example.com/downloads/pic.jpg
QueryHistory	array<object>	No	Historial de conversaciones para la reescritura conversacional de consultas. Solo surte efecto cuando `EnableRewrite` es `true`.
	object	No
role	string	No	El rol del remitente del mensaje. Valores válidos: `user`: Indica que `content` proviene del usuario final. `assistant`: Indica que `content` es una respuesta de la aplicación Model Studio.	user
content	string	No	El contenido del mensaje para el `role` especificado.	¿Qué es Alibaba Cloud Model Studio?

Elementos de respuesta

Elemento	Tipo	Descripción	Ejemplo
	object
Code	string	El código de error.	Index.InvalidParameter
Data	object	Los datos devueltos por la API.
Nodes	array<object>	Una matriz de fragmentos de texto recuperados.
	object	Un objeto de fragmento de texto.
Metadata	any	Un mapa de metadatos para el fragmento de texto. Para bases de conocimientos de búsqueda de documentos, el campo `file_path` en el mapa de metadatos no es aplicable y no debe utilizarse en el código de su aplicación. Cuando recupera datos de una base de conocimientos de búsqueda de documentos, si un fragmento de texto contiene una imagen, su URL se devuelve en el campo `image_url` del mapa de metadatos. Esta URL caduca.	{ "parent": "", "file_path": "https://*", "image_url": [ "http://" ], "nid": "", "title": "Alibaba Cloud Model Studio documentation", "doc_id": "doc_", "content": "Alibaba Cloud Model Studio is a one-stop large model development platform based on Tongyi large models, industry large models, and third-party large models. It provides enterprise customers and individual developers with complete model service tools and a full-link application development suite, pre-configured rich capability plugins, and convenient integration through APIs and SDKs to efficiently build large model applications", "workspace_id": "ws_", "hier_title": "Alibaba Cloud Model Studio documentation", "doc_name": "Alibaba Cloud Model Studio documentation introduction.pdpf", "pipeline_id": "rhd", "_id": "ws_**" }
Score	number	La puntuación de similitud del fragmento de texto, que varía de 0 a 1.	0.3
Text	string	El contenido del fragmento de texto.	Alibaba Cloud Model Studio es una plataforma integral de desarrollo de modelos grandes basada en los modelos grandes Tongyi, modelos industriales y modelos grandes de terceros. Proporciona a clientes empresariales y desarrolladores individuales herramientas completas de servicio de modelos y un conjunto de desarrollo de aplicaciones de extremo a extremo, complementos de capacidades preconfigurados e integración sencilla mediante API y SDK para crear aplicaciones de modelos grandes de manera eficiente.
Message	string	El mensaje de error.	Falta el parámetro obligatorio (%s) o no es válido; compruebe los parámetros de la solicitud.
RequestId	string	El ID de la solicitud.	17204B98-7734-4F9A-8464-2446A84821CA
Status	string	El código de estado HTTP de la respuesta.	200
Éxito	boolean	Indica si la llamada a la API se realizó correctamente. Valores válidos: true: La llamada se realizó correctamente. false: La llamada falló.	true

Ejemplos

Respuesta exitosa

Formato JSON

{
  "Code": "Index.InvalidParameter",
  "Data": {
    "Nodes": [
      {
        "Metadata": "{\n  \"parent\": \"\",\n  \"file_path\": \"https://***\",\n  \"image_url\": [\n    \"http://***\"\n  ],\n  \"nid\": \"***\",\n  \"title\": \"阿里云百炼文档\",\n  \"doc_id\": \"doc_***\",\n  \"content\": \"阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者，提供完整的模型服务工具和全链路应用开发套件，预置丰富的能力插件，提供API及SDK等便捷的集成方式，高效完成大模型应用构建\",\n  \"workspace_id\": \"ws_***\",\n  \"hier_title\": \"阿里云百炼文档\",\n  \"doc_name\": \"阿里云百炼文档介绍.pdpf\",\n  \"pipeline_id\": \"rhd***\",\n  \"_id\": \"ws_***\"\n}",
        "Score": 0.3,
        "Text": "阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者，提供完整的模型服务工具和全链路应用开发套件，预置丰富的能力插件，提供API及SDK等便捷的集成方式，高效完成大模型应用构建。"
      }
    ]
  },
  "Message": "Required parameter(%s) missing or invalid, please check the request parameters.",
  "RequestId": "17204B98-7734-4F9A-8464-2446A84821CA",
  "Status": "200",
  "Success": true
}

Códigos de error

Consulte Códigos de error para obtener una lista completa.

Notas de lanzamiento

Consulte Notas de lanzamiento para obtener una lista completa.