Skip to main content

Retrieve

Obtient des informations à partir d'une base de connaissances spécifiée.

Description de l'opération

  • Comment appeler : Nous vous recommandons d'utiliser la dernière version du SDK Alibaba Cloud Model Studio pour appeler cette API. Le SDK simplifie les appels d'API en gérant le calcul complexe de la signature.
  • Autorisations requises :
    • Utilisateur RAM (sous-compte) : Pour appeler cette API, un utilisateur RAM doit se voir accorder les autorisations d'API pour Alibaba Cloud Model Studio et rejoindre un espace de travail. Vous pouvez utiliser la stratégie AliyunBailianDataFullAccess, qui inclut l'autorisation sfm:Retrieve requise.
    • Compte Alibaba Cloud (compte principal) : Ce compte dispose des autorisations requises par défaut et peut appeler l'API directement.
  • Latence de réponse : Cet appel d'API implique des opérations complexes de récupération et de correspondance, ce qui peut entraîner des temps de réponse plus longs. Nous vous recommandons de configurer des délais d'attente de requête et des stratégies de nouvelle tentative appropriés.
  • Idempotence : Cette API est idempotente.

Testez maintenant

Testez cette API dans OpenAPI Explorer, sans signature manuelle. Les appels réussis génèrent automatiquement du code SDK correspondant à vos paramètres. Téléchargez-le avec une sécurité intégrée des identifiants pour une utilisation locale. Testez cette API dans OpenAPI Explorer, sans signature manuelle. Les appels réussis génèrent automatiquement du code SDK correspondant à vos paramètres. Téléchargez-le avec une sécurité intégrée des identifiants pour une utilisation locale.

Autorisation RAM

Le tableau ci-dessous décrit les autorisations nécessaires pour appeler cette API. Vous pouvez les définir dans une politique Resource Access Management (RAM). Les colonnes du tableau sont détaillées ci-dessous :
  • Action : les actions peuvent être utilisées dans l'élément Action des instructions de politique de permissions RAM pour accorder les autorisations nécessaires à l'exécution de l'opération.
  • API : l'API que vous pouvez appeler pour exécuter l'action.
  • Niveau d'accès : le niveau d'accès prédéfini accordé pour chaque API. Valeurs valides : create, list, get, update et delete.
  • Type de ressource : le type de ressource qui prend en charge l'autorisation pour exécuter l'action. Il indique si l'action prend en charge les permissions au niveau de la ressource. La ressource spécifiée doit être compatible avec l'action. Sinon, la politique sera inefficace.
    • Pour les API avec permissions au niveau de la ressource, les types de ressource requis sont marqués d'un astérisque (*). Spécifiez l'Alibaba Cloud Resource Name (ARN) correspondant dans l'élément Resource de la politique.
    • Pour les API sans permissions au niveau de la ressource, la valeur All Resources est affichée. Utilisez un astérisque (*) dans l'élément Resource de la politique.
  • Clé de condition : les clés de condition définies par le service. La clé permet un contrôle granulaire, applicable aux actions seules ou aux actions associées à des ressources spécifiques. En plus des clés de condition propres au service, Alibaba Cloud fournit un ensemble de clés de condition communes applicables à tous les services pris en charge par RAM.
  • Action dépendante : les actions dépendantes requises pour exécuter l'action. Pour mener à bien l'opération, l'utilisateur RAM ou le rôle RAM doit disposer des permissions pour toutes les actions dépendantes.

Action

Niveau d'accès

Type de ressource

Clé de condition

Action dépendante

sfm:Retrieve

none

*All Resource

*

AucuneAucune

Syntaxe de la requête

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

Paramètres de chemin

Paramètre

Type

Requis

Description

Exemple

WorkspaceId

string

Oui

L'identifiant de l'espace de travail qui contient la base de connaissances. Pour plus d'informations, consultez Comment utiliser les espaces de travail.

llm-3shx2gu255oqxxxx

Paramètres de requête

ParamètreTypeRequisDescriptionExemple
QuerystringNonLa requête, qui correspond à l'invite originale de l'utilisateur. Il n'y a aucune limite sur la longueur de la requête.阿里云百炼平台介绍
DenseSimilarityTopKintegerNonLe nombre de segments de texte similaires top-K à récupérer à l'aide de la récupération vectorielle. Ceci est réalisé en générant une représentation vectorielle de la requête et en recherchant dans la base de connaissances les K segments de texte avec les vecteurs les plus similaires. La valeur doit être un entier compris entre 0 et 100. La somme de DenseSimilarityTopK et SparseSimilarityTopK ne doit pas dépasser 200.Valeur par défaut : 100.100
EnableRerankingbooleanNonIndique si le reclassement doit être activé. Pour plus d'informations, consultez Base de connaissances. Valeurs valides :
  • true : Active le reclassement.
  • false : Désactive le reclassement.
Valeur par défaut : true.Valeurs valides :
  • true : Activé.
  • false : Désactivé.
true
EnableRewritebooleanNonIndique si la réécriture de requête conversationnelle doit être activée. Valeurs valides :
  • true : Active la réécriture de requête conversationnelle.
  • false : Désactive la réécriture de requête conversationnelle.
Valeur par défaut : false.Valeurs valides :
  • true : Activé.
  • false : Désactivé.
false
Rerankarray<object>NonLes configurations de reclassement.
objectNonUn objet contenant les configurations de reclassement.
ModelNamestringNonLe modèle de reclassement à utiliser. La spécification d'un modèle ici remplace le modèle par défaut sélectionné lors de la création de la base de connaissances. Valeurs valides :
  • gte-rerank-hybrid : Effectue le reclassement en utilisant le modèle gte-rerank (hybride).
  • gte-rerank : Effectue le reclassement en utilisant le modèle gte-rerank.
Si vous ne spécifiez pas ce paramètre, le modèle configuré pour la base de connaissances est utilisé.
Utilisez gte-rerank pour le classement sémantique uniquement. Nous recommandons gte-rerank-hybrid si vous avez besoin à la fois des fonctionnalités de classement sémantique et de correspondance de texte pour une pertinence accrue.
Valeurs valides :
  • gte-rerank-hybrid : Effectue le reclassement en utilisant le modèle gte-rerank (hybride).
  • gte-rerank : Effectue le reclassement en utilisant le modèle gte-rerank.
gte-rerank-hybrid
RerankModestringNonCe paramètre n'est pas encore disponible. Ne spécifiez pas de valeur pour celui-ci.[_single.params.Rerank.items.RerankMode.enum.similar: 相似模式。]similar : Mode de similarité. [_single.params.Rerank.items.RerankMode.enum.custom: 自定义模式。]custom : Mode personnalisé. [_single.params.Rerank.items.RerankMode.enum.qa:(默认值) 问答模式。]qa : (Par défaut) Mode Q&R. [parameters.4.schema.items.properties.RerankMode.enumValueTitles.similar: 相似模式。]similar : Mode de similarité. [parameters.4.schema.items.properties.RerankMode.enumValueTitles.custom: 自定义模式。]custom : Mode personnalisé. [parameters.4.schema.items.properties.RerankMode.enumValueTitles.qa:(默认值) 问答模式。]qa : (Par défaut) Mode Q&R.Valeurs valides :
  • similar: 相似模式。 : similar: Similarity mode.
  • custom: 自定义模式。 : custom: Custom mode.
  • qa:(默认值) 问答模式。 : qa: (Default) Q&A mode.
qa
RerankInstructstringNonCe paramètre n'est pas encore disponible. Ne spécifiez pas de valeur pour celui-ci.
RerankMinScorenumberNonLe seuil de similarité pour le reclassement. Seuls les segments de texte avec un score de similarité supérieur à cette valeur sont renvoyés. La valeur doit être comprise entre 0,01 et 1,00 inclus. Ce paramètre remplace le paramètre de seuil de similarité de la base de connaissances.Si non spécifié, le seuil configuré pour la base de connaissances est utilisé.0.20
RerankTopNintegerNonLe nombre de segments de texte les mieux classés à renvoyer après le reclassement. La valeur doit être un entier compris entre 1 et 20. Valeur par défaut : 5.5
Rewritearray<object>NonConfiguration pour la réécriture de requête conversationnelle.
objectNonUn objet contenant les configurations pour la réécriture de requête conversationnelle.
ModelNamestringNonSpécifie le modèle pour la réécriture de requête conversationnelle, qui réécrit automatiquement la requête originale en fonction du contexte de la conversation pour améliorer les résultats de récupération. Valeur valide :
  • conv-rewrite-qwen-1.8b : Le seul modèle actuellement pris en charge pour cette fonctionnalité.
Si ce paramètre n'est pas spécifié, conv-rewrite-qwen-1.8b est utilisé par défaut.Valeurs valides :
  • conv-rewrite-qwen-1.8b : Le modèle conv-rewrite-qwen-1.8b.
conv-rewrite-qwen-1.8b
SparseSimilarityTopKintegerNonLe nombre de segments de texte top-K à récupérer à l'aide de la récupération par mots-clés. Cette fonctionnalité recherche dans la base de connaissances les segments de texte qui correspondent exactement aux mots-clés de la requête. Elle permet de filtrer les segments de texte non pertinents et de fournir des résultats plus précis. La valeur doit être un entier compris entre 0 et 100. La somme de DenseSimilarityTopK et SparseSimilarityTopK ne doit pas dépasser 200.Valeur par défaut : 100.100
IndexIdstringOuiL'identifiant de la base de connaissances. Il s'agit de la valeur Data.Id renvoyée par l'opération CreateIndex.
  • Assurez-vous que la base de connaissances spécifiée existe et n'a pas été supprimée.
5pwe0mxxxx
SaveRetrieverHistorybooleanNonIndique si l'historique de récupération doit être enregistré à des fins de test. Valeurs valides :
  • true : Enregistre l'historique de récupération.
  • false : N'enregistre pas l'historique de récupération.
Valeur par défaut : false.
false
SearchFiltersarray<object>NonSpécifie des conditions de récupération personnalisées, telles que des balises, pour filtrer les résultats de récupération sémantique et exclure les informations non pertinentes. La logique de filtrage est appliquée uniquement lorsque le paramètre is_displayed_chunk_content est défini sur true. Pour plus d'informations, consultez SearchFilters pour une base de connaissances.
objectNonUn objet de condition de recherche.
stringNon
ImagesarrayNonLes URL des images à inclure dans la requête.
stringNonLorsque vous récupérez des informations à partir d'une base de connaissances de Q&R basée sur des images, vous pouvez fournir des URL d'images. Si un index d'images existe dans la base de connaissances, le système convertit l'image d'entrée en vecteur pour récupérer les enregistrements pertinents. Si aucun index d'images n'existe, l'image d'entrée n'est pas utilisée pour la récupération.
Ce champ n'est pas pris en charge pour les bases de connaissances de type recherche de documents ou requête de données. Ce champ n'a aucun effet s'il est spécifié.
Assurez-vous que le lien est accessible publiquement et pointe vers un fichier image valide. Exemple : https://example.com/downloads/pic.jpg
https://example.com/downloads/pic.jpg
QueryHistoryarray<object>NonL'historique de conversation, utilisé pour la réécriture de requête conversationnelle. Ce paramètre est effectif uniquement lorsque EnableRewrite est défini sur true.
objectNon
rolestringNonLe rôle de l'entité qui a envoyé le message.Valeurs valides :
  • user : Indique que le content provient de l'utilisateur final.
  • assistant : Indique que le content est une réponse de l'application Model Studio.
user
contentstringNonLe contenu du message pour le role spécifié.代表一段文本
ExtraobjectNon
uniqueIdstringNon

Éléments de réponse

ÉlémentTypeDescriptionExemple
object
CodestringLe code d'erreur.Index.InvalidParameter
DataobjectLes données métier renvoyées par l'API.
Nodesarray<object>Un tableau de segments de texte récupérés.
objectUn objet de segment de texte.
MetadataanyA map of metadata for the text chunk.
For document search knowledge bases, the file_path field in the metadata map is not applicable and should not be used in your application code.
When you retrieve data from a document search knowledge base, if a text chunk contains an image, its URL is returned in the image_url field of the metadata map. This URL expires.
{
  "parent": "",
  "file_path": "https://***",
  "image_url": [
    "http://***"
  ],
  "nid": "***",
  "title": "阿里云百炼文档",
  "doc_id": "doc_***",
  "content": "阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者,提供完整的模型服务工具和全链路应用开发套件,预置丰富的能力插件,提供API及SDK等便捷的集成方式,高效完成大模型应用构建",
  "workspace_id": "ws_***",
  "hier_title": "阿里云百炼文档",
  "doc_name": "阿里云百炼文档介绍.pdpf",
  "pipeline_id": "rhd***",
  "_id": "ws_***"
}
ScorenumberThe similarity score of the text chunk, ranging from 0 to 1.0.3
TextstringThe content of the text chunk.阿里云百炼是基于通义大模型、行业大模型以及三方大模型的一站式大模型开发平台。面向企业客户和个人开发者,提供完整的模型服务工具和全链路应用开发套件,预置丰富的能力插件,提供API及SDK等便捷的集成方式,高效完成大模型应用构建。
MessagestringLe message d'erreur.Paramètre requis (%s) manquant ou non valide, veuillez vérifier les paramètres de la requête
RequestIdstringL'identifiant de la requête.17204B98-7734-4F9A-8464-2446A84821CA
StatusstringLe code d'état HTTP de la réponse.200
SuccessbooleanIndique si l'appel d'API a réussi. Valeurs valides :
  • true : L'appel a réussi.
  • false : L'appel a échoué.
true

Exemples

正常返回示例 JSON format
{
  "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
}

Codes d'erreur

Consultez Codes d'erreur pour la liste complète.

Notes de version

Consultez Notes de version pour la liste complète.