Récupérez le contenu de la base de connaissances via l'interface Retrieve, qui prend en charge la récupération vectorielle, la recherche en texte intégral et la récupération hybride, avec des stratégies de reclassement (Rerank) configurables.
Prérequis
Une base de connaissances a été créée et les documents ont été importés ; leur statut doit être
Completed(les documents dont le statut estPendingouIndexingne peuvent pas être récupérés).Si les sous-espaces sont activés pour la base de connaissances, vous devez transmettre le paramètre
subspacelors de la récupération, avec un maximum de 32 sous-espaces.Les champs de filtre de métadonnées doivent être définis via
metadatalors de la création de la base de connaissances et ne peuvent pas être ajoutés au moment de l'exécution.Le texte de récupération (
retrievalQuery.text) peut contenir jusqu'à 128 caractères.
Priorité de configuration de la récupération
La configuration de récupération (retrievalConfiguration) de l'interface Retrieve détermine les paramètres effectifs selon la priorité suivante :
|
Priorité |
Source |
Description |
|
1 (la plus élevée) |
Paramètres de l'interface Retrieve |
Le paramètre |
|
2 |
Configuration au niveau de la base de connaissances |
Définie lors de la création de la base de connaissances et 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), renvoie 20 résultats |
La requête de récupération la plus simple nécessite uniquement de transmettre les paramètres knowledgeBaseName et retrievalQuery. Le système utilise automatiquement la configuration de la base de connaissances ou les valeurs par défaut.
Types de récupération
|
Type |
Description |
Scénarios applicables |
|
|
Récupération vectorielle, basée sur la similarité sémantique |
Décrivez les exigences en langage naturel lorsque la compréhension sémantique est nécessaire. Par exemple, « comment installer » peut correspondre à « étapes de déploiement » |
|
|
Recherche en texte intégral, basée sur la correspondance de mots-clés |
Saisissez des mots-clés exacts, des noms propres ou des identifiants |
La récupération vectorielle et la recherche en texte intégral offrent des capacités de rappel complémentaires : la récupération vectorielle excelle dans la compréhension sémantique, tandis que la recherche en texte intégral est performante pour la correspondance exacte. Il est recommandé d'activer simultanément les deux types de récupération et de fusionner les résultats via le reclassement (Rerank).
Stratégies de reclassement
Le reclassement fusionne et classe les résultats issus de la recherche vectorielle et de la recherche en texte intégral, puis renvoie les résultats finaux.
WEIGHT (Fusion pondérée)
Cette méthode applique une pondération proportionnelle aux scores de la recherche vectorielle et de la recherche en texte intégral. Elle convient aux scénarios nécessitant un contrôle précis du ratio de contribution des deux voies de recherche. Nous vous recommandons de l'adopter par défaut.
|
Paramètre |
Type |
Valeur par défaut |
Description |
|
|
double |
0.7 |
Pondération de la recherche vectorielle |
|
|
double |
0.3 |
Pondération de la recherche en texte intégral |
RRF (Reciprocal Rank Fusion)
Cette approche fusionne les résultats de plusieurs voies de recherche en pondérant l'inverse des rangs. Aucun appel de modèle supplémentaire n'est requis, ce qui garantit une faible latence et des performances stables.
|
Paramètre |
Type |
Valeur par défaut |
Description |
|
|
double |
1.0 |
Pondération de la recherche vectorielle |
|
|
double |
1.0 |
Pondération de la recherche en texte intégral |
|
|
int |
60 |
Paramètre de l'algorithme RRF, doit être supérieur à 0 |
Exemple de configuration :
{
"rerankingConfiguration": {
"type": "RRF",
"numberOfResults": 5,
"rrfConfiguration": {
"denseVectorSearchWeight": 0.6,
"fullTextSearchWeight": 0.4,
"k": 20
}
}
}
MODEL (Reclassement par modèle)
Cette stratégie fait appel à un modèle de reclassement (tel que gte-rerank-v2) pour reclasser les résultats candidats. Elle offre la meilleure qualité de classement, mais entraîne une latence supplémentaire et des coûts de calcul plus élevés.
|
Paramètre |
Type |
Valeur par défaut |
Description |
|
|
string |
|
Fournisseur du modèle de reclassement ; seul Bailian est pris en charge actuellement |
|
|
string |
|
Nom du modèle de reclassement |
Recommandations de sélection de stratégie
|
Scénario |
Stratégie recommandée |
|
Cas d'usage généraux sensibles à la latence |
RRF |
|
Besoin de contrôler finement le ratio entre recherche vectorielle et recherche en texte intégral |
WEIGHT |
|
Exigence de qualité de classement maximale avec tolérance à une latence accrue |
MODEL |
Filtrage par métadonnées
Lors de la récupération, utilisez le paramètre filter pour filtrer les résultats selon des conditions de métadonnées et réduire l'éventail des candidats. Les champs de filtre doivent être définis via metadata lors de la création de la base de connaissances. Pour la liste complète des opérateurs, consultez la section API Retrieve Knowledge.
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 appartient à l'ensemble spécifié |
Tous les types |
|
|
La valeur n'appartient pas à l'ensemble spécifié |
Tous les types |
|
|
Correspondance sur le préfixe de la chaîne |
string |
|
|
La chaîne contient la sous-chaîne spécifié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 doivent être satisfaites simultanément |
|
|
Au moins une condition est satisfaite |
|
|
Aucune des conditions n'est satisfaite |
Les opérateurs andAll, orAll et notAll prennent en charge l'imbrication pour construire une logique de filtre combinée complexe.
Exemples de filtres
Requêtez les documents dont la catégorie est « technology » ou « science », avec un score >= 60 et un titre commençant par « product » :
{
"filter": {
"andAll": [
{"in": {"key": "category", "value": ["technology", "science"]}},
{"greaterThanOrEquals": {"key": "score", "value": 60}},
{"startsWith": {"key": "title", "value": "product"}}
]
}
}
Utilisez orAll pour implémenter une logique « OU », en interrogeant les documents dont le statut est « active » ou dont le score est > 90 :
{
"filter": {
"orAll": [
{"equals": {"key": "status", "value": "active"}},
{"greaterThan": {"key": "score", "value": 90}}
]
}
}
Exécution de la récupération
Console
Ouvrez la base de connaissances cible, sélectionnez Retrieval Test dans le volet de navigation de gauche, puis suivez les étapes ci-dessous pour vérifier les résultats de la récupération :
Saisissez le texte de recherche dans la zone de saisie Content. Si des sous-espaces sont activés pour la base de connaissances, renseignez également le nom du sous-espace.
Dans Search Type, sélectionnez Vector Retrieval et/ou Full-text Retrieval.
Définissez les valeurs Vector TopK, Full-text TopK et Rerank TopK (vous pouvez conserver les valeurs par défaut).
Sélectionnez une Rerank Strategy : Model, Weight ou RRF. Si vous choisissez Weight, vous pouvez définir les pondérations pour la récupération vectorielle et textuelle.
Si des champs de métadonnées sont définis pour la base de connaissances, ajoutez des conditions de filtrage sur les métadonnées.
Cliquez sur Run Retrieval pour afficher le contenu des fragments trouvés, leur source et leur score de pertinence dans Retrieved Chunks.
Pour votre premier test, nous vous recommandons d’utiliser les paramètres par défaut. Une fois que vous avez confirmé que le contenu cible est bien récupéré, ajustez progressivement les valeurs TopK et la stratégie de reclassement.
SDK
Python
Exemple minimal : aucun paramètre de récupération n’est transmis ; la configuration au niveau de la base de connaissances ou les valeurs par défaut du système sont utilisées :
from tablestore_agent_storage import AgentStorageClient
client = AgentStorageClient(
api_key="<your-api-key>",
ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
ots_instance_name="<instance-name>",
)
resp = client.retrieve({
"knowledgeBaseName": "product_docs_kb",
"retrievalQuery": {"type": "TEXT", "text": "What are the installation steps for the product"}
})
for r in resp["data"]["retrievalResults"]:
print(f"[{r['score']:.4f}] {r['content'][:80]}...")
Exemple complet : définissez les paramètres de récupération dans la requête pour remplacer la configuration au niveau de la base de connaissances :
resp = client.retrieve({
"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": [
{"in": {"key": "category", "value": ["product docs"]}}
]
}
}
})
for result in resp["data"]["retrievalResults"]:
print(f"[score={result['score']:.4f}] {result['content'][:100]}...")
print(f" source: {result['ossKey']}, chunkId: {result['chunkId']}")
Utilisez les classes Model pour construire la requête afin de bénéficier d’une meilleure complétion de code et de la vérification des types dans l’IDE :
from tablestore_agent_storage import AgentStorageClient
from tablestore_agent_storage.models import (
RetrieveRequest, RetrievalQuery, RetrievalQueryType
)
client = AgentStorageClient(
api_key="<your-api-key>",
ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
ots_instance_name="<instance-name>",
)
resp = client.retrieve(RetrieveRequest(
knowledge_base_name="product_docs_kb",
retrieval_query=RetrievalQuery(
text="What are the installation steps for the product",
type=RetrievalQueryType.TEXT
)
))
TypeScript
import { AgentStorageClient } from '@tablestore/agent-storage';
const client = new AgentStorageClient({
apiKey: '<your-api-key>',
endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
instanceName: '<instance-name>',
});
const resp = await client.retrieve({
knowledgeBaseName: 'product_docs_kb',
retrievalQuery: { type: 'TEXT', text: 'What are the installation steps for the product' },
});
for (const r of resp.data.retrievalResults) {
console.log(`[${r.score.toFixed(4)}] ${r.content.slice(0, 80)}...`);
}
API
Appelez Retrieve pour effectuer la récupération. Pour obtenir la liste complète des champs de requête, des champs de réponse et la description des opérateurs de filtre, consultez Retrieve Knowledge API.
Le texte de recherche
textpeut contenir jusqu’à 128 caractères (lettres ou caractères chinois). Un dépassement entraîne une erreur. Si vos besoins métier l’exigent, soumettez un ticket ou rejoignez le groupe DingTalk d’échange technique Tablestore 36165029092 pour contacter le support technique.Les champs de filtre doivent être définis comme métadonnées lors de la création de la base de connaissances ; sinon, les conditions de filtre ne seront pas prises en compte.
La valeur
kde RRF doit être supérieure à 0 ; sinon, une erreurVALIDATION_ERRORsera signalée.Les documents dont le statut est
PendingouIndexingne peuvent pas faire l’objet d’une récupération. Vous devez attendre que le statut passe àCompleted.Une fois les sous-espaces activés pour une base de connaissances, vous devez transmettre le paramètre
subspace; sinon, une erreur sera signalée.
Ajustement de la récupération
Relations entre les paramètres numberOfResults
Le processus de récupération comporte trois niveaux de numberOfResults . Comprendre leurs relations est essentiel pour l’ajustement :
denseVectorSearchConfiguration.numberOfResults = N1 ← Vector retrieval recall count
fullTextSearchConfiguration.numberOfResults = N2 ← Full-text retrieval recall count
rerankingConfiguration.numberOfResults = N3 ← Final return count after Rerank
N1 et N2 déterminent la taille du pool de candidats. Une valeur plus élevée augmente le taux de rappel, mais aussi le coût de calcul.
N3 détermine le nombre de résultats finalement retournés. En général, N3 < N1 et N3 < N2.
Configuration de départ recommandée : N1 = N2 = 20, N3 = 5–10. Ajustez progressivement en fonction des résultats obtenus.
Sélection du type de récupération
|
Scénario |
Type de récupération recommandé |
Description |
|
Poser des questions en langage naturel |
|
La récupération vectorielle capture la sémantique, tandis que la récupération textuelle garantit la correspondance des mots-clés. |
|
Saisir des mots-clés ou des identifiants exacts |
Privilégier |
La récupération vectorielle n’est pas sensible à la correspondance exacte. |
|
Scénarios de compréhension purement sémantique |
Privilégier |
Par exemple, « how to install » correspond à « deployment steps ». |
Recommandations d’utilisation des filtres de métadonnées
Le filtre réduit l’étendue des candidats avant la récupération, ce qui améliore à la fois la précision et les performances.
Les champs de filtre doivent être définis comme métadonnées lors de la création de la base de connaissances et ne peuvent pas être ajoutés à l’exécution.
Pour le filtrage par plage de dates, utilisez le type
dateplutôt que le typestringafin de prendre en charge les opérateurs de comparaison de plage.