API d'analyse des requêtes - OpenSearch - Centre de documentation Alibaba Cloud

Cette rubrique présente les détails de l'API du service d'analyse des requêtes.

Nom du service

ID du service

Description du service

Limite de QPS pour les appels API (compte Alibaba Cloud et utilisateurs RAM)

Service d'analyse des requêtes

ops-query-analyze-001

Fournit des services d'analyse du contenu des requêtes, alimentés par de grands modèles de langage et des capacités de traitement du langage naturel (NLP). Le service inclut la détection d'intention, l'expansion de questions similaires et le traitement NL2SQL pour les requêtes saisies par les utilisateurs, améliorant ainsi efficacement les performances de récupération et de génération de réponses dans les scénarios RAG.

Pour utiliser le service NL2SQL, configurez d'abord les informations telles que les schémas de table et des exemples de requêtes dans la console. Pour plus d'informations, consultez Configurer un service NL2SQL. Une fois la configuration effectuée, appelez le service Analyse des requêtes - NL2SQL via l'API en suivant les instructions de cette rubrique.

Remarque

Pour demander une limite de QPS API plus élevée, soumettez un ticket au support technique.

Obtenir les identifiants d'authentification

La plateforme ouverte AI Search nécessite une clé API pour l'authentification. Pour obtenir des instructions, consultez Obtenir une clé API.
Obtenir le point de terminaison du service

Vous pouvez appeler le service via le réseau public ou un VPC. Pour plus de détails, consultez Obtenir le point de terminaison du service.

Description générale

Le corps de la requête ne doit pas dépasser 8 Mo.

Méthode de requête

POST

URL

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

host : adresse pour appeler le service. Prend en charge l'appel des services API via le réseau public et le VPC. Pour plus d'informations, consultez Obtenir un point de terminaison de service.
service_id : ID de service intégré au système, par exemple ops-query-analyze-001.

Paramètres de requête

Paramètres d'en-tête

Authentification par clé API

Paramètre

Type

Obligatoire

Description

Exemple de valeur

Content-Type

String

Oui

Type de requête : application/json

application/json

Authorization

String

Oui

Clé API

Bearer OS-d1**2a

Paramètres du corps

Paramètre	Type	Obligatoire	Description	Exemple de valeur
query	String	Oui	Contenu de cette requête.	Combien de personnes ?
history	List<Message>	Non	Messages historiques.	[{ "content": "Où se trouve la capitale de la Chine", "role": "user" }, { "content": "Pékin", "role": "assistant" }]
history.content	String	Non	Contenu du message.	Où se trouve la capitale de la Chine
history.role	String	Non	Expéditeur du message. Valeurs possibles pour les rôles : system, user, assistant.	user
functions	List<Function>	Non	Les fonctions activées et leurs paramètres correspondants. Valeurs valides : pre : Prétraitement. intent : Détection d'intention. similar_query : Expansion de requêtes similaires nl2sql : Langage naturel vers SQL Remarque : Par défaut, pre, intent et similar_query sont activés. Lorsque nl2sql est activé, intent et similar_query sont désactivés par défaut.
functions[].name	String	Non	Si vous spécifiez une fonction, vous devez spécifier name.
functions[].parameters	Map	Non	Les paramètres de la fonction.
functions[].parameters.enable	boolean	Non	Indique si la fonction est activée.	true

Paramètres de réponse

Paramètre	Type	Description	Exemple de valeur
request_id	String	Identifiant unique attribué par le système pour un appel API.	A5B25952-4406-45BF-99EC-E8020246****
latency	Float/Int	Durée de la requête, en ms.	10
result.query	String	Requête traitée.	Combien de personnes
result.queries	List<String>	Requêtes alternatives générées.	[ "Combien de personnes à Pékin" ]
result.intent	String	Résultat de la détection d'intention.	Paire Q&R
result.sql	Map	Résultat nl2sql.

Exemple de requête 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"
                  }
                }
              ]
            }'

Exemple de réponse

Exemple de réponse normale

{
  "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;"
      }
    }
}

Exemple de réponse anormale

En cas d'erreur dans la requête d'accès, le résultat de sortie indique la raison de l'erreur via les champs code et message.

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

Description des codes d'état

Code d'état HTTP

Code d'erreur

Description

200

Requête réussie, y compris les scénarios d'échec de tâche. Le statut réel de la tâche doit être déterminé à partir de result.status.

404

BadRequest.TaskNotExist

La tâche n'existe pas.

400

InvalidParameter

Requête invalide.

500

InternalServerError

Erreur interne.