Utilisez l'API Retrieve pour effectuer une recherche sémantique dans une base de connaissances et renvoyer la liste des fragments les plus pertinents par rapport au texte de la requête.
Prérequis
Vous avez créé une instance AgentStorage dont l'état est
normal. Vous disposez du endpoint et du nom de l'instance.Vous avez créé une API Key.
La base de connaissances à interroger existe déjà et contient des documents à l'état
completed.
Paramètres de la requête
|
Paramètre |
Type |
Description |
|
|
string |
Nom de la base de connaissances (obligatoire) |
|
|
list<string> |
Liste des sous-espaces (32 maximum). Obligatoire si la fonctionnalité de sous-espace est activée. |
|
|
object |
Requête de récupération (obligatoire) |
|
|
string |
Type de requête (obligatoire). Seule la valeur |
|
|
string |
Texte de la requête de récupération (obligatoire). 128 caractères maximum. |
|
|
object |
Configuration de la récupération. Si ce paramètre est omis, le système utilise la configuration de la base de connaissances ou les valeurs par défaut. |
|
|
list<string> |
Type de récupération |
|
|
int |
Nombre de résultats renvoyés par la recherche vectorielle (100 maximum). |
|
|
int |
Nombre de résultats renvoyés par la recherche en texte intégral (100 maximum). |
|
|
object |
Configuration du reclassement |
|
|
object |
Condition de filtrage des métadonnées |
### Priorité de la configuration de récupération
La configuration de récupération (retrievalConfiguration) de l'API Retrieve détermine les paramètres effectifs selon l'ordre de priorité suivant :
|
Priorité |
Source |
Description |
|
1 (la plus élevée) |
Paramètres de l'API Retrieve |
Le paramètre |
|
2 |
Configuration de la base de connaissances |
Définie lors de la création de la base de connaissances. Modifiable à tout moment via UpdateKnowledgeBase. |
|
3 (la plus basse) |
Valeurs par défaut du système |
Récupération hybride (vectorielle + texte intégral), fusion pondérée WEIGHT (vecteur 0,7 : texte intégral 0,3), renvoyant 20 résultats. |
Si la fonctionnalité de sous-espace est désactivée, une requête de récupération minimale ne nécessite que les paramètres knowledgeBaseName et retrievalQuery. Si elle est activée, vous devez également fournir le paramètre subspace. En l'absence de configuration de récupération explicite, le système utilise la configuration de la base de connaissances ou les valeurs par défaut.
### Opérateurs pris en charge par le filtre
#### Opérateurs de comparaison
|
Opérateur |
Symbole |
Description |
Types applicables |
|
|
= |
Égal à |
Tous les types |
|
|
≠ |
Différent de |
Tous les types |
|
|
> |
Supérieur à |
long, double, date |
|
|
≥ |
Supérieur ou égal à |
long, double, date |
|
|
< |
Inférieur à |
long, double, date |
|
|
≤ |
Inférieur ou égal à |
long, double, date |
#### Opérateurs d'ensemble et de correspondance
|
Opérateur |
Description |
Types applicables |
|
|
La valeur figure dans l'ensemble donné. |
Tous les types |
|
|
La valeur ne figure pas dans l'ensemble donné. |
Tous les types |
|
|
Correspondance sur le préfixe de la chaîne. |
string |
|
|
La chaîne contient la sous-chaîne recherchée. |
string |
|
|
Le champ de type liste contient l'élément spécifié. |
type list |
#### Opérateurs de combinaison logique
|
Opérateur |
Description |
|
|
Toutes les conditions sont satisfaites simultanément. |
|
|
Au moins une condition est satisfaite. |
|
|
Aucune des conditions n'est satisfaite. |
Les opérateurs andAll, orAll et notAll acceptent l'imbrication, ce qui permet de construire une logique de filtrage combinée complexe.
Exemple de requête
Lors de l'utilisation de l'authentification par API Key, transmettez le nom de l'instance et la clé API via les en-têtes de requête x-ots-instancename et x-ots-apikey.
curl -X POST https://<endpoint>/Retrieve \
-H "x-ots-instancename: <instance-name>" \
-H "x-ots-apikey: <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
"knowledgeBaseName": "product_docs_kb",
"subspace": ["default"],
"retrievalQuery": {"type": "TEXT", "text": "What are the installation steps for the product"},
"retrievalConfiguration": {
"searchType": ["DENSE_VECTOR", "FULL_TEXT"],
"denseVectorSearchConfiguration": {"numberOfResults": 10},
"fullTextSearchConfiguration": {"numberOfResults": 10},
"rerankingConfiguration": {
"type": "RRF",
"numberOfResults": 5,
"rrfConfiguration": {"denseVectorSearchWeight": 0.6, "fullTextSearchWeight": 0.4, "k": 60}
},
"filter": {
"andAll": [
{"greaterThanOrEquals": {"key": "score", "value": 60}}
]
}
}
}'Réponse
|
Champ |
Type |
Description |
|
|
list<object> |
Liste des résultats de récupération, triés par score de pertinence décroissant. |
|
|
string |
ID du document parent |
|
|
int |
ID du fragment |
|
|
string |
Chemin OSS du document parent |
|
|
float |
Score de pertinence ; une valeur plus élevée indique une pertinence plus forte. |
|
|
string |
Contenu original du fragment |
|
|
string |
Sous-espace |
|
|
object |
Métadonnées du document |
{
"code": "SUCCESS",
"data": {
"retrievalResults": [
{
"ossKey": "oss://example-bucket/docs/manual.pdf",
"docId": "fc6ed97f-28ad-4dc0-9b73-bf4a7d67ab65",
"chunkId": 0,
"chunkType": "TEXT",
"subspace": "default",
"score": 0.6630394798989444,
"content": "Product installation steps: 1. Download and extract the installation package. 2. Follow the installation wizard to complete the installation. 3. Start the product and confirm that the installation success page is displayed.", "metadata": {"author": "Zhang San", "date": "2026-01-22 10:00:59", "score": 80}
}
]
},
"message": "success"
}