Aller au contenu principal
Dernière mise à jour le

Utilisez Knowledge Assistant pour créer un chatbot de haute qualité sur vos documents

Cette page explique comment utiliser Knowledge Assistant pour créer un chatbot questions-réponses basé sur vos documents et améliorer sa qualité à l'aide des commentaires en langage naturel de vos experts en la matière.

Qu'est-ce que l'assistant de connaissances ?​

Utilisez Knowledge Assistant pour créer un chatbot qui peut répondre aux questions concernant vos documents et fournir des réponses de haute qualité avec des citations. Knowledge Assistant utilise une IA avancée et suit une approche Instructed Retriever pour pallier les limites de l'approche traditionnelle de génération augmentée par récupération (RAG) et fournir les réponses de la plus haute qualité basées sur la documentation que vous fournissez. Il prend en charge les documents dans plusieurs langues.

Knowledge Assistant est idéal pour prendre en charge les cas d'utilisation suivants :

  • Répondez aux questions des utilisateurs en vous basant sur la documentation du produit.
  • Répondez aux questions des employés liées aux politiques RH.
  • Répondez aux demandes des clients en vous basant sur les bases de connaissances de support.

Knowledge Assistant vous permet d'améliorer la qualité de l'agent de conversation et d'ajuster son comportement en fonction des commentaires en langage naturel de vos experts en la matière. Fournissez des questions et des directives directement dans l'expérience, et partagez votre agent pour permettre aux autres de collaborer et d'améliorer les performances de l'agent.

Knowledge Assistant crée un endpoint d'agent que vous pouvez utiliser en aval pour vos applications. Par exemple, l'image ci-dessous montre comment vous pouvez interagir avec l'Endpoint en discutant avec lui dans AI Playground. Posez des questions à l'agent concernant vos documents, et l'agent répondra avec des citations.

Endpoint de l'Assistant de connaissances dans Playground.

Knowledge Assistant utilise le stockage default pour stocker des Transformations de données temporaires, des points de contrôle de modèle et des métadonnées internes qui alimentent chaque agent. Lors de la suppression de l'agent, toutes les données associées à l'agent sont supprimées du stockage default.

Exigences​

  • Un Workspace qui inclut les éléments suivants :

  • Un workspace dans l'une des régions prises en charge.

  • Vous devez disposer de données d'entrée prêtes à l'emploi. Vous avez le choix parmi les options suivantes :

    • Fichiers dans un volume Unity Catalog ou un répertoire de volume. Les types de fichiers pris en charge sont txt, pdf, md, ppt/pptx et doc/docx.
    • Une table Unity Catalog avec une colonne de fichier. Consultez l'étape 1 : Configurer votre agent pour les exigences de schéma et les détails de configuration.
    • Un index de recherche IA qui utilise l'un des modèles d'incorporation suivants : databricks-gte-large-en, databricks-bge-large-en ou databricks-qwen3-embedding-0-6b. Consultez Créer un index de recherche IA.

Créer un agent Knowledge Assistant​

Accédez à Icône des agents. **Agents** dans le volet de navigation de gauche de votre workspace. Cliquez sur **Créer un agent**, et sélectionnez **Knowledge Assistant**.

Étape 1 : Configurez votre agent​

Configurez votre agent et fournissez-lui des sources de connaissances à utiliser pour répondre aux questions.

  1. Dans le champ Nom , saisissez un nom pour votre agent.

  2. Dans le champ Description , décrivez ce que votre agent peut faire.

  3. Dans le panneau Source de connaissances , ajoutez votre source de connaissances. Vous pouvez choisir de fournir des fichiers dans un volume, des fichiers dans une table ou un index de recherche IA.

Pour les fichiers d’un volume ou d’un répertoire Unity Catalog, les types de fichiers suivants sont pris en charge : txt, pdf, md, ppt/pptx et doc/docx. Les fichiers de plus de 50 Mo sont automatiquement ignorés pendant l'ingestion et ne sont pas inclus dans la base de connaissances. Les fichiers PDF, DOC, DOCX, PPT et PPTX de plus de 500 pages sont également ignorés. Pour les fichiers PowerPoint, chaque diapositive compte comme une page. Les fichiers TXT et MD n’ont pas de limite de pages.

  1. Sous Type , sélectionnez Fichiers dans un volume .
  2. Dans le champ **Source**, sélectionnez le volume Unity Catalog ou le répertoire de volume qui contient vos fichiers.
  3. Dans le champ Nom , saisissez un nom pour votre source de connaissances.
  4. Sous Décrivez le contenu , décrivez le contenu que contient la source de connaissances pour aider l'agent à comprendre quand utiliser cette source de données.

  1. (Facultatif) Si vous souhaitez ajouter d'autres sources de connaissances, cliquez sur Ajouter une source de connaissances . Vous pouvez fournir jusqu'à 10 sources de connaissances.

  2. (Facultatif) Dans le champ **Instructions**, spécifiez des directives sur la manière dont l'agent doit répondre.

  3. Cliquez sur Créer l'agent .

La création de votre agent et la synchronisation des sources de connaissances que vous avez fournies peuvent prendre quelques heures. Lorsque l'agent est prêt, le panneau latéral droit affiche les sources de connaissances synchronisées.

important

Si vous mettez à jour ou ajoutez des fichiers à vos sources de connaissances, vous devez cliquer sur Icône de synchronisation. Synchroniser pour que l'agent prenne en compte les modifications. La synchronisation est effectuée de manière incrémentielle. Par exemple, si vous ajoutez un nouveau fichier à un volume Unity Catalog précédemment synchronisé, la synchronisation ne traitera que le fichier nouvellement ajouté.

Tout utilisateur disposant de l'autorisation CAN MANAGE sur l'assistant de connaissances peut synchroniser les sources de connaissances.

Étape 2 : Testez votre agent​

Une fois que votre agent a terminé sa création, testez-le en discutant avec lui. L'agent doit répondre avec des citations pour les questions liées à ses sources de connaissances.

  1. Commencez à discuter avec votre agent directement dans l'onglet **tab**.
  2. (Facultatif) Vous pouvez également cliquer sur Ouvrir dans AI Playground pour discuter avec celui-ci dans AI Playground.
  3. Saisissez une question pour votre agent.
  4. Évaluez sa réponse :
    1. Cliquez sur **Afficher les réflexions** pour voir comment votre agent a abordé la réponse à la question.
    2. Cliquez sur Afficher la trace pour voir la trace complète. Vous pouvez ajouter des étiquettes aux traces dans l'interface utilisateur pour suivre les évaluations de qualité pendant le processus de développement.
    3. Cliquez sur **Voir les sources** pour voir les fichiers cités par l’agent comme références. Cela ouvre un panneau latéral avec une liste de sources à examiner.

Si vous êtes satisfait(e) des performances de votre agent, continuez à l’utiliser tel quel.

Étape 3 : améliorer la qualité​

Knowledge Assistant peut ajuster le comportement de l'agent en fonction des commentaires en langage naturel. Recueillez les commentaires d'experts via la page de configuration pour améliorer la qualité de votre agent. La collecte de données étiquetées pour votre agent peut améliorer sa qualité et son comportement.

Dans l'onglet Exemples , ajoutez les questions que vos utilisateurs poseront ou les questions auxquelles votre agent a déjà mal répondu. Vous pouvez également importer des données étiquetées directement depuis une table Unity Catalog.

  1. Ajouter des questions à étiqueter :

    1. Cliquez sur + Ajouter pour ajouter une question.
    2. Dans la fenêtre contextuelle **Ajouter une question**, saisissez votre question.
    3. Cliquez sur **Ajouter**. La question devrait apparaître dans l'interface utilisateur.
    4. Répétez jusqu'à ce que vous ayez ajouté toutes les questions que vous souhaitez évaluer.
    5. Pour supprimer une question, cliquez sur le menu kebab, puis sur **Supprimer**.

  2. Une fois que vous avez fini d'ajouter vos questions, vous pouvez partager l'agent avec d'autres personnes pour examen afin de vous aider à créer un dataset étiqueté de haute qualité. Dans le coin supérieur droit, cliquez sur le menu kebab Icône du menu kebab. pour gérer les autorisations.

    Afin que les experts puissent accéder et fournir des commentaires, vous devez leur accorder les autorisations suivantes :

    • autorisation CAN_MANAGE de la page de configuration de l'agent

  3. Partagez un Link vers votre page de configuration de Knowledge Assistant pour recueillir les commentaires d'experts.

  4. Pour étiqueter les données, cliquez sur une question et ajoutez des Directives dans le volet qui apparaît. Les directives s'appliquent juste après avoir été enregistrées.

  5. Testez l'agent à nouveau dans la page de configuration ou l'AI Playground pour voir ses performances améliorées. Si nécessaire, ajoutez d'autres questions et directives pour continuer à améliorer le comportement.

(Facultatif) Importer et exporter des données étiquetées​

Pour importer de nouvelles questions et des commentaires directement à partir d'une table Unity Catalog :

  1. Cliquez sur **Importer**.

  2. Dans le champ Source , sélectionnez la table Unity Catalog contenant les données étiquetées.

    La table doit avoir le schéma suivant :

    • eval_id: string

    • request: string

    • guidelines: array

      • items: string

    • metadata: string

    • tags: string

  3. Cliquez sur **Importer**.

Les nouvelles questions et directives sont Merge dans le tableau de données étiquetées à droite.

Pour exporter des données étiquetées en tant que table Unity Catalog :

  1. Cliquez sur Exporter .
  2. Dans le champ Schéma , sélectionnez l'emplacement du schéma Unity Catalog pour y enregistrer les données.
  3. Dans le champ **Nom de la table**, saisissez un nom pour la table.
  4. Cliquez sur Exporter.

Une nouvelle table est créée avec les données étiquetées.

Gérer les sources de connaissances​

Après avoir créé un Knowledge Assistant, vous pouvez ajouter, supprimer et mettre à jour les sources de connaissances sans recréer l'agent. Seul le créateur du Knowledge Assistant peut ajouter ou supprimer des sources de connaissances. Tout utilisateur disposant de l'autorisation CAN MANAGE peut mettre à jour le nom et la description de la source de connaissances, et synchroniser les sources de connaissances.

Vous pouvez rédiger plusieurs modifications à la fois — par exemple, ajouter une nouvelle source, en supprimer une existante et mettre à jour la description d'une autre — puis appliquer toutes les modifications simultanément lorsque vous cliquez sur Enregistrer et mettre à jour .

Ajouter une source de connaissances​

  1. Sur la page de configuration de l'agent, accédez à l'onglet **Sources tab**.
  2. Cliquez sur + Ajouter sous les cartes de source de connaissances existantes.
  3. Sélectionnez le type de source de connaissances à ajouter (fichiers dans un volume Unity Catalog, fichiers dans une table Unity Catalog ou index de recherche AI) et configurez-le comme décrit dans Étape 1 : Configurez votre agent.
  4. Cliquez sur **Enregistrer et mettre à jour**.

L'agent commence la synchronisation de la nouvelle source de connaissances. Les sources de connaissances existantes et leurs données ne sont pas affectées.

remarque

Vous pouvez fournir jusqu'à 10 sources de connaissances par assistant de connaissances. L'ajout d'une source de fichier start une Job d'ingestion qui peut prendre du temps en fonction du volume de données.

Supprimez une source de connaissances​

  1. Sur la page de configuration de l'agent, accédez à l'onglet **Sources tab**.
  2. Passez la souris sur la carte de la source de connaissances que vous souhaitez supprimer et cliquez sur l'icône de la corbeille Icône Corbeille. dans le coin supérieur droit.
  3. Dans la boîte de dialogue de confirmation, cliquez sur Confirmer pour supprimer la source.
  4. Cliquez sur **Enregistrer et mettre à jour**.

La source de connaissances et ses données associées sont supprimées de l'agent. Cette action n’est pas facilement réversible car le fait de rajouter la source nécessite la réingestion des données.

important

Vous ne pouvez pas supprimer la dernière source de connaissances restante. Un assistant de connaissances doit toujours avoir au moins une source de connaissances.

Mettre à jour les détails de la source de connaissances​

Vous pouvez mettre à jour le nom et la description d’une source de connaissances existante. Ces détails aident l'agent à comprendre quand utiliser chaque source.

  1. Sur la page de configuration de l'agent, accédez à l'onglet **Sources tab**.
  2. Survolez la carte de la source de connaissances que vous souhaitez modifier et cliquez sur l'icône en forme de crayon.
  3. Mettez à jour les champs Nom ou Description .
  4. Cliquez sur **Enregistrer et mettre à jour**.

Gérer les autorisations​

Par default, seuls les auteurs d'agents et les administrateurs de Workspace disposent des autorisations pour l'agent. Pour permettre à d'autres utilisateurs de modifier ou de query votre agent, vous devez leur accorder explicitement l'autorisation.

Pour gérer les autorisations de votre agent :

  1. Ouvrez votre agent sur la page Agents .

  2. En haut, cliquez sur le Icône du menu kebab. menu kebab.

  3. Cliquez sur Gérer les autorisations .

  4. Dans la fenêtre Permission Settings , sélectionnez l’utilisateur, le groupe ou le Service Principal.

  5. Sélectionnez l'autorisation à accorder :

    • Peut gérer : permet de gérer l’agent, y compris la définition des autorisations, la modification de la configuration de l’agent et l’amélioration de sa qualité.
    • Peut query : Permet d'interroger l'Endpoint de l'agent dans AI Playground et via l'API. Les utilisateurs disposant uniquement de cette autorisation ne peuvent ni afficher ni modifier l'agent sur la page Agents.

  6. Cliquez sur **Ajouter**.

  7. Cliquez sur Enregistrer .

important

Seul le créateur de l'assistant de connaissances peut ajouter ou supprimer des sources de connaissances. Tout utilisateur disposant de l'autorisation CAN MANAGE sur l'assistant de connaissances peut synchroniser les sources de connaissances et mettre à jour le nom et la description de la source de connaissances.

Interroger l'endpoint de l'agent​

Sur la page de l'agent, cliquez sur **Endpoint** pour ouvrir l'endpoint de l'agent et voir les détails.

Il existe plusieurs façons de query l'endpoint de l'assistant de connaissances créé. Utilisez les exemples de code fournis dans l'AI Playground comme point de départ :

  1. Cliquez sur Ouvrir dans Playground .
  2. Depuis le Terrain de jeux, cliquez sur Obtenir le code .
  3. Choisissez comment vous souhaitez utiliser l’Endpoint :
    • Sélectionnez Curl API pour un exemple de code permettant d'interroger l'Endpoint à l'aide de curl.
    • Sélectionnez API Python pour un exemple de code permettant d'interagir avec l'endpoint à l'aide de Python.

Gérer les assistants de connaissances à l'aide du SDK Databricks​

Vous pouvez utiliser le Databricks SDK pour Python pour créer et gérer par programmation des assistants de connaissances et leurs sources de connaissances. Pour la liste complète des opérations d'API disponibles, consultez la référence de l'API Knowledge Assistants.

Créer un assistant de connaissances​

L'exemple suivant crée un nouvel assistant de connaissances avec un nom d'affichage, une description et des instructions.

Python
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.knowledgeassistants import KnowledgeAssistant

w = WorkspaceClient()

knowledge_assistant = KnowledgeAssistant(
    display_name="<display-name>",
    description="<description>",
    instructions="<instructions>",
)
created = w.knowledge_assistants.create_knowledge_assistant(knowledge_assistant=knowledge_assistant)
print(created)

Remplacez <display-name>, <description> et <instructions> par les valeurs de votre assistant de connaissances.

Gérer les sources de connaissances​

Vous pouvez ajouter, supprimer et mettre à jour des sources de connaissances sur un assistant de connaissances existant à l'aide du SDK.

Ajouter une source de connaissances​

L’exemple suivant ajoute une source de connaissances à partir de fichiers d’un volume Unity Catalog à un assistant de connaissances existant.

Python
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.knowledgeassistants import KnowledgeSource, FilesSpec

w = WorkspaceClient()

files_source = KnowledgeSource(
    display_name="<knowledge-source-name>",
    description="<knowledge-source-description>",
    source_type="files",
    files=FilesSpec(
        path="<volume-path>",
    ),
)

created_source = w.knowledge_assistants.create_knowledge_source(
    parent="knowledge-assistants/<knowledge-assistant-id>",
    knowledge_source=files_source,
)
print(created_source)

Pour ajouter une source d'index de recherche IA à la place, utilisez IndexSpec:

Python
from databricks.sdk.service.knowledgeassistants import KnowledgeSource, IndexSpec

index_source = KnowledgeSource(
    display_name="<knowledge-source-name>",
    description="<knowledge-source-description>",
    source_type="index",
    index=IndexSpec(
        index_name="<catalog.schema.index-name>",
        text_col="<text-column>",
        doc_uri_col="<doc-uri-column>",
    ),
)

created_source = w.knowledge_assistants.create_knowledge_source(
    parent="knowledge-assistants/<knowledge-assistant-id>",
    knowledge_source=index_source,
)
print(created_source)

Supprimez une source de connaissances​

L'exemple suivant supprime une source de connaissances d'un assistant de connaissances.

Python
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

w.knowledge_assistants.delete_knowledge_source(
    name="knowledge-assistants/<knowledge-assistant-id>/knowledge-sources/<knowledge-source-id>",
)

Mettre à jour une source de connaissances​

L'exemple suivant met à jour le nom d'affichage et la description d'une source de connaissances existante.

Python
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.knowledgeassistants import KnowledgeSource

w = WorkspaceClient()

updated_source = w.knowledge_assistants.update_knowledge_source(
    name="knowledge-assistants/<knowledge-assistant-id>/knowledge-sources/<knowledge-source-id>",
    knowledge_source=KnowledgeSource(
        display_name="<new-name>",
        description="<new-description>",
    ),
    update_mask="display_name,description",
)
print(updated_source)

Champs autorisés dans update_mask: display_name, description.

Synchroniser les sources de connaissances​

Après avoir ajouté ou mis à jour des fichiers dans une source de connaissances basée sur des fichiers (tels qu'un volume ou une table Unity Catalog), Trigger une synchronisation pour mettre à jour l'index de l'assistant de connaissances avec le contenu de fichier le plus récent.

remarque

Les sources de connaissances basées sur l'index se mettent à jour automatiquement et ne nécessitent pas de synchronisation manuelle.

Python
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

w.knowledge_assistants.sync_knowledge_sources(
    name="knowledge-assistants/<knowledge-assistant-id>",
)

Migrer un assistant de connaissances entre les espaces de travail​

Vous pouvez utiliser le SDK pour répliquer un assistant de connaissances d'un workspace à un autre. L'exemple suivant récupère un assistant de connaissances du workspace source et le recrée, ainsi que ses sources de connaissances, dans le workspace cible.

remarque

Les sources de connaissances référencées dans le Workspace cible (telles que les index AI Search ou les volumes Unity Catalog) doivent déjà exister dans le Workspace cible avant que vous ne créiez les sources de connaissances.

Python
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.knowledgeassistants import (
    Example,
    KnowledgeAssistant,
    KnowledgeSource,
    IndexSpec,
    FilesSpec,
)

# Retrieve the knowledge assistant from the source workspace
source_client = WorkspaceClient()
ka = source_client.knowledge_assistants.get_knowledge_assistant(name="<source-knowledge-assistant-name>")
print(ka.display_name, ka.description, ka.instructions)

# Set up the client for the target workspace
target_client = WorkspaceClient(
    host="<target-workspace-url>",
    token="<target-workspace-token>",
)

# Create the knowledge assistant in the target workspace
knowledge_assistant = KnowledgeAssistant(
    display_name=ka.display_name,
    description=ka.description,
    instructions=ka.instructions,
)
created = target_client.knowledge_assistants.create_knowledge_assistant(knowledge_assistant=knowledge_assistant)
print(created)

# Re-create knowledge sources in the target workspace
index_source = KnowledgeSource(
    display_name="<knowledge-source-name>",
    description="<knowledge-source-description>",
    source_type="index",
    index=IndexSpec(
        index_name="<catalog.schema.index-name>",
        text_col="<text-column>",
        doc_uri_col="<doc-uri-column>",
    ),
)

files_source = KnowledgeSource(
    display_name="<knowledge-source-name>",
    description="<knowledge-source-description>",
    source_type="files",
    files=FilesSpec(
        path="<volume-path>",
    ),
)

created_index_source = target_client.knowledge_assistants.create_knowledge_source(
    parent=created.name,
    knowledge_source=index_source,
)
print(created_index_source)

created_files_source = target_client.knowledge_assistants.create_knowledge_source(
    parent=created.name,
    knowledge_source=files_source,
)
print(created_files_source)

# Re-create examples in the target knowledge assistant
for ex in source_client.knowledge_assistants.list_examples(parent=ka.name):
    example = source_client.knowledge_assistants.get_example(name=ex.name)
    target_client.knowledge_assistants.create_example(
        parent=created.name,
        example=Example(
            question=example.question,
            guidelines=example.guidelines,
        ),
    )

Remplacez les valeurs d'espace réservé par les valeurs appropriées pour vos Workspace source et cible. Le <source-knowledge-assistant-name> suit le format knowledge-assistants/<knowledge-assistant-id>.

Évaluer votre Assistant de connaissances​

Ce notebook montre comment évaluer un assistant de connaissances à l'aide de datasets d'évaluation organisés et d'évaluateurs personnalisés.

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks

Limitations​

  • Les fichiers de plus de 50 Mo sont automatiquement ignorés lors de l'ingestion et ne sont pas inclus dans la base de connaissances.
  • Les fichiers PDF, DOC, DOCX, PPT et PPTX de plus de 500 pages sont ignorés pendant l'ingestion. Pour les fichiers PowerPoint (PPT, PPTX), chaque diapositive compte comme une page. Les fichiers TXT et MD n'ont pas de limite de page. L'ingestion utilise ai_parse_document, qui a une limite de 500 pages par document.
  • Les fichiers dont le nom commence par un trait de soulignement (_) ou un point (.) sont automatiquement ignorés lors de l'ingestion et ne sont pas inclus dans la base de connaissances.
  • Pour les sources de connaissances qui utilisent des fichiers d'une table Unity Catalog, seule la colonne de contenu sélectionnée est ingérée. D'autres colonnes dans la source de connaissances de la table ne sont pas utilisées.
  • Seuls les index de recherche AI qui utilisent l'un des modèles d'embedding suivants sont pris en charge : databricks-gte-large-en, databricks-bge-large-en ou databricks-qwen3-embedding-0-6b.
Sur cette page