Gérer les bases de connaissances - Tablestore - Centre de documentation Alibaba Cloud

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

Important

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.

Remarque

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.

Remarque

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.

Remarque

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

Avertissement

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.