Análisis de consultas - OpenSearch - Centro de documentación de Alibaba Cloud

Este tema proporciona detalles sobre la API del servicio de análisis de consultas.

Nombre del servicio

ID del servicio

Descripción del servicio

Límite de QPS para llamadas a la API (cuenta de Alibaba Cloud y usuarios de RAM)

Servicio de análisis de consultas

ops-query-analyze-001

Proporciona servicios de análisis de contenido de consultas impulsados por modelos de lenguaje grande y capacidades de NLP. El servicio incluye detección de intenciones, expansión de preguntas similares y procesamiento NL2SQL para las consultas de entrada del usuario, lo que mejora eficazmente el rendimiento de recuperación y generación de respuestas en escenarios RAG.

Para utilizar el servicio NL2SQL, primero debe configurar información como esquemas de tablas y ejemplos de consultas en la consola. Para obtener más información, consulte Configure an NL2SQL service. Después de la configuración, puede llamar al servicio Query Analysis - NL2SQL a través de la API siguiendo las instrucciones de este documento.

Nota

Para solicitar un límite de QPS de API mayor, envíe un ticket al soporte técnico.

Obtención de credenciales de autenticación

La plataforma abierta AI Search requiere una clave de API para la autenticación. Para consultar las instrucciones, consulte Get an API key.
Obtención del endpoint del servicio

Puede llamar al servicio a través de la red pública o una VPC. Para más detalles, consulte Get the service endpoint.

Descripción general

El cuerpo de la solicitud no debe exceder los 8 MB.

Método de solicitud

POST

URL

{host}/v3/openapi/workspaces/{workspace_name}/query-analyze/{service_id}

host: La dirección para llamar al servicio; admite llamadas a servicios API tanto a través de la red pública como de VPC. Para obtener más información, consulte Obtain a service endpoint.
service_id: El ID de servicio integrado del sistema, como ops-query-analyze-001.

Parámetros de solicitud

Parámetros de encabezado

Autenticación mediante API-KEY

Parámetro	Tipo	Obligatorio	Descripción	Valor de ejemplo
Content-Type	String	Sí	Tipo de solicitud: application/json	application/json
Authorization	String	Sí	API-Key	Bearer OS-d1**2a

Parámetros del cuerpo

Parámetro	Tipo	Obligatorio	Descripción	Valor de ejemplo
query	String	Sí	Contenido de esta solicitud.	How many people?
history	List<Message>	No	Mensajes del historial.	[{ "content": "Where is the capital of China", "role": "user" }, { "content": "Beijing", "role": "assistant" }]
history.content	String	No	Contenido del mensaje.	Where is the capital of China
history.role	String	No	Remitente del mensaje; valores opcionales actuales para roles: system, user, assistant.	user
unctions	List<Function>	No	Las funciones habilitadas y sus parámetros correspondientes. Valores válidos: pre: Preprocesamiento. intent: Detección de intenciones. similar_query: Expansión de consultas similares. nl2sql: Lenguaje natural a SQL. Nota: De forma predeterminada, pre, intent y similar_query están habilitadas. Cuando se habilita nl2sql, intent y similar_query se deshabilitan de forma predeterminada.
functions[].name	String	No	Si especifica una función, debe especificar name.
functions[].parameters	Map	No	Los parámetros de la función.
functions[].parameters.enable	boolean	No	Especifica si se debe habilitar la función.	true

Parámetros de respuesta

Parámetro	Tipo	Descripción	Valor de ejemplo
request_id	String	El identificador único asignado por el sistema para una llamada a la API.	A5B25952-4406-45BF-99EC-E8020246****
latency	Float/Int	Duración de la solicitud, en ms.	10
result.query	String	Solicitud procesada.	How many people
result.queries	List<String>	Consultas alternativas generadas.	[ "How many people in Beijing" ]
result.intent	String	Resultado de la detección de intenciones.	Q&A pair
result.sql	Map	El resultado de nl2sql.

Ejemplo de solicitud con curl

curl -XPOST -H"Content-Type: application/json" 
\http://****.opensearch.aliyuncs.com/v3/openapi/workspaces/default/query-analyze/ops-query-analyze-001\
    -H "Authorization: Bearer Your API-Key" \
    -d'{
      "query":"What class is Jack in",
      "history":[
          {
            "role":"user",
            "content":"Where is the capital of China"
          },
          {
            "role":"assistant",
            "content":"Beijing"
          }
        ],
        "functions":[
          {
            "name":"pre",
            "parameters":
              {
                "enable":true
              }
          },
          {
            "name":"intent",
            "parameters":
              {
                "enable":true
              }
            },
            {
              "name":"similar_query",
              "parameters":
                {
                  "enable":true
                }
              },
              {
                "name":"nl2sql",
                "parameters":
                  {
                    "enable":true,
                    "config_name":"n_1726047726"
                  }
                }
              ]
            }'

Ejemplo de respuesta

Ejemplo de respuesta normal

{
  "request_id":"023FC760-E273-4163-B2DA-5CF28E2A****",
  "latency":6383,
  "usage":{
      "total_tokens":1082,
      "output_tokens":41,
      "input_tokens":1041
    },
    "result":{
      "query":"What class is Jack from",
      "queries":[
          "The class Jack from"
      ],
      "intent":"Q&A",
      "sql":{
          "text":"SELECT students.class FROM students WHERE students.name = 10002;"
      }
    }
}

Ejemplo de respuesta anómala

En caso de error en la solicitud de acceso, el resultado indicará el motivo del error mediante code y message.

{
  "request_id":"19C54DAA-AD50-4B37-A48C-912A8F82****",
  "latency":0,
  "code":"InvalidParameter",
  "message":"Required parameter: query missing or invalid, please check the request parameter."
}

Descripción de códigos de estado

Código de estado HTTP	Código de error	Descripción
200	-	Solicitud exitosa, incluidos escenarios de fallo de tarea. El estado real de la tarea debe determinarse a partir de result.status.
404	BadRequest.TaskNotExist	La tarea no existe.
400	InvalidParameter	Solicitud no válida.
500	InternalServerError	Error interno.