Dans le service de stockage de connaissances AgentStorage, une base de connaissances est le conteneur de premier niveau pour les documents, les fragments et les configurations de récupération. Vous pouvez créer, interroger, lister, mettre à jour et supprimer des bases de connaissances depuis la console AgentStorage, via les SDK ou en appelant des opérations API.
Créer une base de connaissances
Avant de créer une base de connaissances, vérifiez que les conditions préalables suivantes sont remplies :
Créez une instance AgentStorage et récupérez son endpoint ainsi que son nom d'instance. Les appels SDK et API mentionnés dans cette rubrique nécessitent ces informations.
Préparez une clé API. Les clients SDK présentés dans cette rubrique utilisent l'authentification par clé API.
Pour importer des documents depuis un stockage local ou Object Storage Service (OSS), vérifiez que votre compte dispose d'un bucket OSS dans la même région et que l'autorisation OSS est configurée.
Paramètres de base
Le tableau suivant décrit les paramètres configurables lors de la création d'une base de connaissances et indique s'ils sont modifiables après la création :
| Paramètre | Description | Modifiable après création |
| Nom | Doit commencer par une lettre et contenir uniquement des lettres, des chiffres et des traits de soulignement. La longueur doit être comprise entre 1 et 64 caractères, et le nom doit être unique au sein de la même instance. | Non |
| Description et tags | Décrit l'objectif de la base de connaissances. La description peut atteindre 4 Ko et la longueur totale des tags ne peut pas dépasser 4 Ko. | Oui |
| Groupe de ressources | Groupe de ressources auquel appartient la base de connaissances. | — |
| Schéma de métadonnées | Définit des attributs de document supplémentaires, tels que des champs personnalisés pour la source, la catégorie et le numéro de version, utilisables pour filtrer les résultats de récupération. Prend en charge les types string, long, double, boolean et date, ainsi que leurs types _list correspondants. Les noms de champs peuvent atteindre 128 octets, ne doivent pas contenir . et ne peuvent pas utiliser de champs réservés (_uid, _id, _type, etc.). Jusqu'à 200 champs sont pris en charge. |
Non |
| Sous-espace | Isole les documents au sein d'une même base de connaissances par ligne métier, projet ou locataire. Une fois activé, toutes les opérations sur les documents et les requêtes de récupération doivent spécifier un sous-espace. | Non |
| Multimodal | Active l'ingestion d'images et la récupération multimodale. | Non |
| Modèle d'embedding | Détermine la capacité de compréhension sémantique de la récupération vectorielle. Le modèle Bailian text-embedding-v4 (1 024 dimensions) est utilisé par défaut. Les modèles personnalisés sont également pris en charge. |
Non |
| Configuration de récupération | Spécifie le type de récupération et la stratégie de reclassement. La valeur par défaut est la récupération hybride qui combine la récupération vectorielle et la recherche en texte intégral. Le reclassement utilise par défaut la fusion pondérée WEIGHT (vecteur 0,7 : texte intégral 0,3). | Oui |
Les définitions des champs de métadonnées, la configuration d'embedding et l'activation du sous-espace ne peuvent pas être modifiées après la création. Planifiez-les entièrement avant de créer une base de connaissances. Pour changer le modèle d'embedding ou ajouter/supprimer des champs de métadonnées, supprimez et recréez la base de connaissances.
Console
Connectez-vous à la console AgentStorage, cliquez sur Knowledge Base Management, puis sur Create Knowledge Base.
Saisissez un nom conforme aux règles de dénomination décrites dans la section Paramètres de base, ajoutez une description si nécessaire et sélectionnez un groupe de ressources.
Configurez le schéma de métadonnées : ajoutez des champs personnalisés pour le filtrage de la récupération, tels que l'auteur, la catégorie et le numéro de version, et sélectionnez les types de champs.
Activez Subspace pour l'isolation des données multi-locataires et Multimodal pour l'ingestion d'images et la récupération multimodale selon vos besoins.
Dans Advanced settings, personnalisez le modèle d'embedding, le nombre de résultats récupérés, le type de récupération et la stratégie de reclassement. Si vous n'avez pas d'exigences de réglage spécifiques, utilisez d'abord la configuration par défaut.
Cliquez sur OK pour créer la base de connaissances.
Une fois la base de connaissances créée, elle apparaît dans la liste des bases de connaissances.
Si une invite d'autorisation OSS s'affiche, effectuez l'autorisation avant de continuer.
SDK
Python
L'exemple de code suivant montre comment créer une base de connaissances :
from tablestore_agent_storage import AgentStorageClient
# Initialize the client (API key authentication)
client = AgentStorageClient(
api_key="<your-api-key>",
ots_endpoint="https://<instance>.<region>.ots.aliyuncs.com",
ots_instance_name="<instance-name>",
)
# Create a knowledge base (Bailian text-embedding-v4 and hybrid vector and full-text retrieval are used by default)
client.create_knowledge_base({
"knowledgeBaseName": "product_docs_kb",
"description": "Knowledge base for product documentation",
"metadata": [
{"name": "author", "type": "string"},
{"name": "category", "type": "string"},
{"name": "publish_date", "type": "date"}
],
"embeddingConfiguration": {
"provider": "bailian",
"model": "text-embedding-v4",
"dimension": 1024
},
"retrievalConfiguration": {
"searchType": ["DENSE_VECTOR", "FULL_TEXT"],
"denseVectorSearchConfiguration": {"numberOfResults": 10},
"fullTextSearchConfiguration": {"numberOfResults": 10},
"rerankingConfiguration": {
"type": "WEIGHT",
"numberOfResults": 5,
"weightConfiguration": {
"denseVectorSearchWeight": 0.7,
"fullTextSearchWeight": 0.3
}
}
}
})TypeScript
L'exemple de code suivant montre comment créer une base de connaissances :
import { AgentStorageClient } from '@tablestore/agent-storage';
// Initialize the client (API key authentication)
const client = new AgentStorageClient({
apiKey: '<your-api-key>',
endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
instanceName: '<instance-name>',
});
// Create a knowledge base
await client.createKnowledgeBase({
knowledgeBaseName: 'product_docs_kb',
description: 'Knowledge base for product information',
metadata: [
{ name: 'author', type: 'string' },
{ name: 'category', type: 'string' },
],
});Dans cet exemple, embeddingConfiguration et retrievalConfiguration sont omis ; le modèle d'embedding et la configuration de récupération par défaut sont donc utilisés.
API
Appelez CreateKnowledgeBase pour créer une base de connaissances. Pour obtenir la liste complète des champs de requête et la description de la réponse, consultez CreateKnowledgeBase.
Interroger les détails d'une base de connaissances
Interrogez la configuration complète d'une base de connaissances spécifique, y compris son nom, sa description, ses définitions de métadonnées, sa configuration d'embedding et sa configuration de récupération. Pour afficher toutes les bases de connaissances de l'instance actuelle en une seule fois, consultez la section Lister les bases de connaissances.
Console
Sur la page de liste des bases de connaissances, choisissez ··· > Details dans le coin supérieur droit de la carte de la base de connaissances cible pour afficher sa configuration complète.
SDK
Python
L'exemple de code suivant montre comment interroger les détails d'une base de connaissances :
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.describe_knowledge_base({
"knowledgeBaseName": "product_docs_kb"
})
data = resp["data"]
print(f"Name: {data['knowledgeBaseName']}")
print(f"Embedding: {data['embeddingConfiguration']}")
print(f"Retrieval configuration: {data['retrievalConfiguration']}")TypeScript
L'exemple de code suivant montre comment interroger les détails d'une base de connaissances :
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.describeKnowledgeBase({
knowledgeBaseName: 'product_docs_kb',
});
console.log(resp.data);API
Appelez DescribeKnowledgeBase pour interroger les détails d'une base de connaissances. Pour obtenir la liste complète des champs, consultez DescribeKnowledgeBase.
Lister les bases de connaissances
Utilisez la pagination pour lister toutes les bases de connaissances de l'instance actuelle.
La valeur maximale de maxResults est 100. Les valeurs supérieures à 100 renvoient INVALID_PARAMETER.
Console
Sur la page Knowledge Base Management, affichez la liste de toutes les bases de connaissances, y compris leurs noms, descriptions et heures de création.
SDK
Python
L'exemple de code suivant montre comment lister les bases de connaissances par page :
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>",
)
# Get the first page
resp = client.list_knowledge_base({"maxResults": 10})
for kb in resp["data"]["knowledgeBases"]:
print(f"{kb['knowledgeBaseName']} - {kb.get('description', '')}")
# Get the next page
next_token = resp["data"].get("nextToken")
if next_token:
resp = client.list_knowledge_base({
"maxResults": 10,
"nextToken": next_token
})TypeScript
L'exemple de code suivant montre comment lister les bases de connaissances :
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.listKnowledgeBase({ maxResults: 10 });
for (const kb of resp.data.knowledgeBases) {
console.log(kb.knowledgeBaseName, kb.description);
}API
Appelez ListKnowledgeBase pour lister les bases de connaissances. Pour obtenir la liste complète des champs, consultez ListKnowledgeBase.
Mettre à jour une base de connaissances
Mettez à jour la description, les tags ou la configuration de récupération d'une base de connaissances. Vous devez spécifier au moins l'un des paramètres suivants : description, tags ou retrievalConfiguration. Les paramètres embeddingConfiguration et metadata ne peuvent pas être modifiés via cette opération. Pour changer le modèle d'embedding ou ajouter/supprimer des champs de métadonnées, supprimez et recréez la base de connaissances.
Après modification de retrievalConfiguration, les requêtes Retrieve ultérieures qui n'incluent pas de configuration de récupération utiliseront la nouvelle configuration. Les requêtes incluant explicitement une configuration ne sont pas affectées.
Console
Sur la page de liste des bases de connaissances, choisissez ··· > Settings dans le coin supérieur droit de la carte de la base de connaissances cible, puis cliquez sur Edit pour mettre à jour la description, les tags et la configuration de récupération.
SDK
Python
L'exemple de code suivant montre comment mettre à jour une base de connaissances :
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>",
)
client.update_knowledge_base({
"knowledgeBaseName": "product_docs_kb",
"description": "Updated description",
"tags": ["live"],
"retrievalConfiguration": {
"searchType": ["DENSE_VECTOR", "FULL_TEXT"],
"rerankingConfiguration": {
"type": "RRF",
"numberOfResults": 10,
"rrfConfiguration": {"k": 60}
}
}
})TypeScript
L'exemple de code suivant montre comment mettre à jour une base de connaissances :
import { AgentStorageClient } from '@tablestore/agent-storage';
const client = new AgentStorageClient({
apiKey: '<your-api-key>',
endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
instanceName: '<instance-name>',
});
await client.updateKnowledgeBase({
knowledgeBaseName: 'product_docs_kb',
description: 'Updated description',
tags: ['live'],
});Cet exemple met à jour uniquement la description et les tags, sans modifier la configuration de récupération.
API
Appelez UpdateKnowledgeBase pour mettre à jour une base de connaissances. Pour obtenir la liste complète des champs, consultez UpdateKnowledgeBase.
Supprimer une base de connaissances
Cette opération est irréversible. La suppression d'une base de connaissances entraîne également la suppression de tous les documents et données de fragments qu'elle contient.
Console
Sur la page de liste des bases de connaissances, cliquez sur ··· dans le coin supérieur droit de la carte de la base de connaissances cible et sélectionnez Delete. Saisissez le nom de la base de connaissances pour confirmer la suppression.
SDK
Python
L'exemple de code suivant montre comment supprimer une base de connaissances :
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>",
)
client.delete_knowledge_base({
"knowledgeBaseName": "product_docs_kb"
})TypeScript
L'exemple de code suivant montre comment supprimer une base de connaissances :
import { AgentStorageClient } from '@tablestore/agent-storage';
const client = new AgentStorageClient({
apiKey: '<your-api-key>',
endpoint: 'https://<instance>.<region>.ots.aliyuncs.com',
instanceName: '<instance-name>',
});
await client.deleteKnowledgeBase({ knowledgeBaseName: 'product_docs_kb' });API
Appelez DeleteKnowledgeBase pour supprimer une base de connaissances. Pour obtenir la liste complète des champs, consultez DeleteKnowledgeBase.