Pular para o conteúdo principal
Última atualização em

Use o Knowledge Assistant para criar um chatbot de alta qualidade para seus documentos

Esta página descreve como usar o Assistente de Conhecimento para criar um chatbot de perguntas e respostas sobre seus documentos e melhorar sua qualidade com base no feedback em linguagem natural de seus especialistas no assunto.

O que é o Assistente de Conhecimento?​

Use o Knowledge Assistant para criar um chatbot que possa responder a perguntas sobre seus documentos e fornecer respostas de alta qualidade com citações. O Knowledge Assistant usa AI avançada e segue uma abordagem Instructed Retriever para lidar com as limitações da abordagem tradicional de geração aumentada de recuperação (RAG) e fornecer respostas da mais alta qualidade com base na documentação que você fornece. Ele é compatível com documentos em vários idiomas.

O Assistente de Conhecimento é ideal para oferecer suporte aos seguintes casos de uso:

  • Responda às perguntas do usuário com base na documentação do produto.
  • Responder às perguntas dos funcionários relacionadas a políticas de RH.
  • Responda às consultas de clientes com base em bases de conhecimento de suporte.

O Assistente de Conhecimento permite que você melhore a qualidade do agente de bate-papo e ajuste seu comportamento com base no feedback em linguagem natural de seus especialistas no assunto. Forneça perguntas e diretrizes diretamente na experiência e compartilhe seu agente para permitir que outros colaborem e melhorem o desempenho do agente.

O Knowledge Assistant cria um endpoint de agente que pode ser usado em downstream para suas aplicações. Por exemplo, a imagem abaixo mostra como interagir com o endpoint conversando com ele no AI Playground. Faça perguntas ao agente relacionadas aos seus documentos, e o agente responderá com citações.

Endpoint do Assistente de conhecimento no Playground.

O Knowledge Assistant usa armazenamento default para armazenar transformações de dados temporárias, pontos de verificação de modelo e metadados internos que potencializam cada agente. Ao excluir o agente, todos os dados associados ao agente são removidos do armazenamento default.

Requisitos​

  • Um workspace que inclui o seguinte:

  • Um workspace em uma das regiões compatíveis.

  • É preciso ter dados de entrada prontos para uso. É possível escolher entre as seguintes opções:

    • Arquivos em um volume ou diretório de volume do Unity Catalog. Os tipos de arquivo compatíveis são txt, pdf, md, ppt/pptx e doc/docx.
    • Uma tabela do Unity Catalog com uma coluna de arquivo. Consulte o passo 1: Configure seu agente para os requisitos de esquema e detalhes de configuração.
    • Um índice de Pesquisa de AI que usa um dos seguintes modelos de incorporação: databricks-gte-large-en, databricks-bge-large-en ou databricks-qwen3-embedding-0-6b. Consulte Criar um índice de Pesquisa de AI.

Criar um agente do Knowledge Assistant​

Vá para Ícone de Agentes. Agentes no painel de navegação esquerdo do seu workspace. Clique em Create Agent e selecione Assistente de Conhecimento .

O passo 1: Configure seu agente​

Configure seu agente e forneça fontes de conhecimento para que ele use para responder a perguntas.

  1. No campo Nome , insira um nome para seu agente.

  2. No campo Descrição , descreva o que seu agente pode fazer.

  3. No painel Fonte de conhecimento , adicione sua fonte de conhecimento. O senhor pode optar por fornecer arquivos em um volume, arquivos em uma tabela ou um índice de Pesquisa de AI.

Para arquivos em um volume ou diretório do Unity Catalog, os seguintes tipos de arquivo são compatíveis: txt, pdf, md, ppt/pptx e doc/docx. Arquivos maiores que 50 MB são automaticamente ignorados durante a ingestão e não são incluídos na base de conhecimento. Arquivos PDF, DOC, DOCX, PPT e PPTX com mais de 500 páginas também são ignorados. Para arquivos do PowerPoint, cada slide conta como uma página. Arquivos TXT e MD não têm limite de página.

  1. Em Tipo, selecione Arquivos em um Volume.
  2. No campo Origem , selecione o volume do Unity Catalog ou o diretório de volume que contém seus arquivos.
  3. No campo Nome , insira um nome para sua fonte de conhecimento.
  4. Em Descreva o conteúdo, descreva o conteúdo que a fonte de conhecimento contém para ajudar o agente a entender quando usar esta fonte de dados.

  1. (Opcional) Caso queira adicionar mais fontes de conhecimento, clique em Adicionar fonte de conhecimento . É possível fornecer até 10 fontes de conhecimento.

  2. (Opcional) No campo Instruções , especifique diretrizes sobre como o agente deve responder.

  3. Clique em Criar Agente .

A criação do seu agente e a sincronização das fontes de conhecimento fornecidas podem levar algumas horas. Quando o agente estiver pronto, o painel do lado direito exibe as fontes de conhecimento sincronizadas.

importante

Se você atualizar ou adicionar arquivos às suas fontes de conhecimento, você precisa clicar em Ícone de Sincronização. ** Sincronizar** para que o agente detecte as alterações. A sincronização é feita incrementalmente. Por exemplo, se você adicionar um novo arquivo a um volume do Unity Catalog sincronizado anteriormente, a sincronização processará apenas o arquivo recém-adicionado.

Qualquer usuário com permissão CAN MANAGE no assistente de conhecimento pode sincronizar fontes de conhecimento.

O Passo 2: teste seu agente​

Depois que seu agente terminar de ser compilado, teste-o conversando com ele. O agente deve responder com citações para perguntas relacionadas às suas fontes de conhecimento.

  1. Comece a conversar com seu agente diretamente na tab **Build**.
  2. (Opcional) Você também pode clicar em Abrir no Playground para conversar com ele no AI Playground.
  3. Insira uma pergunta para seu agente.
  4. Avalie sua resposta:
    1. Clique em view pensamentos para ver como seu agente abordou a resposta à pergunta.
    2. Clique em Visualizar rastreamento para ver o rastreamento completo. Você pode adicionar rótulos a rastreamentos na interface do usuário para acompanhar as avaliações de qualidade durante o processo de desenvolvimento.
    3. Clique em view fontes para ver quais arquivos o agente cita como referências. Isso abre um painel lateral com uma lista de fontes para você revisar.

Se você estiver satisfeito com o desempenho do seu agente, continue usando o agente como está.

O passo 3: Melhorar a qualidade​

O Knowledge Assistant pode ajustar o comportamento do agente com base no feedback em linguagem natural. Colete feedback de especialistas por meio da página de configuração para melhorar a qualidade do seu agente. A coleta de dados com rótulo para o seu agente pode melhorar a qualidade e o comportamento dele.

Na tab Exemplos , adicione as perguntas que seus usuários farão ou perguntas que seu agente errou anteriormente. Alternativamente, você também pode importar dados com rótulo diretamente de uma tabela do Unity Catalog.

  1. Adicionar perguntas para rótulo:

    1. Clique em + Adicionar para adicionar uma pergunta.
    2. No modal Adicionar uma pergunta , insira sua pergunta.
    3. Clique em Adicionar . A pergunta deve aparecer na interface do usuário.
    4. Repita até que você tenha adicionado todas as perguntas que deseja avaliar.
    5. Para excluir uma pergunta, clique no menu kebab e selecione **Excluir**.

  2. Depois de adicionar suas perguntas, você pode compartilhar o agente com outras pessoas para revisão, a fim de ajudar a construir um dataset rotulado de alta qualidade. No canto superior direito, clique no menu kebab Ícone de menu kebab. para gerenciar permissões.

    Para que os especialistas possam acessar e fornecer feedback, é necessário conceder a eles as seguintes permissões:

    • Permissão CAN_MANAGE da página de configuração do agente

  3. Compartilhe um link para sua página de configuração do Assistente de Conhecimento para coletar feedback de especialistas.

  4. Para adicionar um rótulo aos dados, clique em uma pergunta e adicione Diretrizes no painel que aparece. As diretrizes se aplicam logo após serem salvas.

  5. Teste o agente novamente na página de configuração ou no AI Playground para observar seu desempenho aprimorado. Se necessário, adicione mais perguntas e diretrizes para continuar aprimorando o comportamento.

(Opcional) Importar e exportar dados com rótulos​

Para importar novas perguntas e feedback diretamente de uma tabela do Unity Catalog:

  1. Clique em Importar .

  2. No campo **Origem**, selecione a tabela do Unity Catalog que contém os dados com rótulo.

    A tabela deve ter o seguinte esquema:

    • eval_id: string

    • request: string

    • guidelines: array

      • items: string

    • metadata: string

    • tags: string

  3. Clique em Importar .

Novas perguntas e diretrizes são merge na tabela de dados com rótulo à direita.

Para exportar dados com rótulo como uma tabela do Unity Catalog:

  1. Clique em Exportar .
  2. No campo Esquema , selecione o local do esquema do Unity Catalog para salvar os dados.
  3. No campo Nome da tabela , insira um nome para a tabela.
  4. Clique em Exportar.

Uma nova tabela é criada com os dados com rótulo.

Gerenciar fontes de conhecimento​

Depois de criar um assistente de conhecimento, você pode adicionar, remover e atualizar fontes de conhecimento sem recriar o agente. Somente o criador do assistente de conhecimento pode adicionar ou remover fontes de conhecimento. Qualquer usuário com permissão CAN MANAGE pode atualizar o nome e a descrição da fonte de conhecimento e sincronizar as fontes de conhecimento.

É possível rascunhar várias alterações de uma vez — por exemplo, adicionar uma nova origem, remover uma existente e atualizar a descrição de outra — e então aplicar todas as alterações simultaneamente ao clicar em Salvar e Atualizar .

Adicionar uma fonte de conhecimento​

  1. Na página de configuração do agente, vá para a tab **Sources**.
  2. Clique em + Adicionar abaixo dos cartões de fonte de conhecimento existentes.
  3. Selecione o tipo de fonte de conhecimento a adicionar (arquivos em um volume do Unity Catalog, arquivos em uma tabela do Unity Catalog ou índice de pesquisa de AI) e configure-o conforme descrito em O passo 1: Configure seu agente.
  4. Clique em Salvar e Atualizar .

O agente começa a sincronizar a nova fonte de conhecimento. As fontes de conhecimento existentes e seus dados não são afetados.

nota

É possível fornecer até 10 fontes de conhecimento por assistente de conhecimento. Adicionar uma fonte de arquivo começa um Job de ingestão que pode levar tempo, dependendo do volume de dados.

Remover uma fonte de conhecimento​

  1. Na página de configuração do agente, vá para a tab **Sources**.
  2. Passe o mouse sobre o cartão da fonte de conhecimento que você deseja remover e clique no ícone da lixeira Ícone da lixeira. no canto superior direito.
  3. Na caixa de diálogo de confirmação, clique em Confirmar para remover a origem.
  4. Clique em Salvar e Atualizar .

A fonte de conhecimento e seus dados associados são removidos do agente. Esta ação não é facilmente reversível porque a readição da fonte exige a reingestão dos dados.

importante

Não é possível remover a última fonte de conhecimento restante. Um assistente de conhecimento deve sempre ter pelo menos uma fonte de conhecimento.

Atualizar detalhes da fonte de conhecimento​

Você pode atualizar o nome e a descrição de uma fonte de conhecimento existente. Esses detalhes ajudam o agente a entender quando usar cada fonte.

  1. Na página de configuração do agente, vá para a tab **Sources**.
  2. Passe o mouse sobre o cartão da fonte de conhecimento que se deseja editar e clique no ícone de lápis.
  3. Atualize os campos de **Nome** ou **Descrição**.
  4. Clique em Salvar e Atualizar .

Gerenciar permissões​

Por default, somente autores de agentes e administradores de workspace têm permissões para o agente. Para permitir que outros usuários editem ou consultem o agente, é necessário conceder permissão explicitamente.

Para gerenciar permissões no seu agente:

  1. Abra o agente na página **Agentes**.

  2. Na parte superior, clique no menu kebab Ícone de menu kebab..

  3. Clique em Gerenciar permissões .

  4. Na janela **Configurações de permissão**, selecione o usuário, grupo ou entidade de serviço.

  5. Selecione a permissão a conceder:

    • Pode Gerenciar : Permite gerenciar o agente, incluindo a configuração de permissões, a edição da configuração do agente e a melhoria de sua qualidade.
    • Pode Consultar : Permite consultar o endpoint do agente no AI Playground e por meio da API. Usuários com apenas esta permissão não podem view ou editar o agente na página Agentes.

  6. Clique em Adicionar .

  7. Clique em Salvar .

importante

Somente o criador do assistente de conhecimento pode adicionar ou remover fontes de conhecimento. Qualquer usuário com permissão CAN MANAGE no assistente de conhecimento pode sincronizar fontes de conhecimento e atualizar o nome e a descrição da fonte de conhecimento.

Consultar o endpoint do agente​

Na página do agente, clique em Endpoint para abrir o endpoint do agente e ver detalhes.

Existem várias maneiras de consultar o endpoint do assistente de conhecimento criado. Use os exemplos de código fornecidos no AI Playground como ponto de partida:

  1. Clique em Abrir no playground .
  2. No Playground, clique em Obter código .
  3. Escolha como você deseja usar o endpoint:
    • Selecione Curl API para obter um exemplo de código para consultar o endpoint usando curl.
    • Selecione API Python para um exemplo de código para interagir com o endpoint usando Python.

Gerenciar assistentes de conhecimento usando o SDK do Databricks​

É possível usar o SDK do Databricks para Python para criar e gerenciar programaticamente assistentes de conhecimento e suas fontes de conhecimento. Para a lista completa de operações de API disponíveis, consulte a referência de API do Knowledge Assistants.

Criar um assistente de conhecimento​

O exemplo a seguir cria um novo assistente de conhecimento com um nome de exibição, descrição e instruções.

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)

Substitua <display-name>, <description> e <instructions> pelos valores do seu assistente de conhecimento.

Gerenciar fontes de conhecimento​

Você pode adicionar, remover e atualizar fontes de conhecimento em um assistente de conhecimento existente usando o SDK.

Adicionar uma fonte de conhecimento​

O exemplo a seguir adiciona uma fonte de conhecimento de arquivos em um volume do Unity Catalog a um assistente de conhecimento existente.

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)

Para adicionar uma fonte de Índice de Pesquisa de AI, em vez disso, use 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)

Remover uma fonte de conhecimento​

O exemplo a seguir exclui uma fonte de conhecimento de um assistente de conhecimento.

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>",
)

Atualizar uma fonte de conhecimento​

O exemplo a seguir atualiza o nome de exibição e a descrição de uma fonte de conhecimento existente.

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)

Campos permitidos em update_mask: display_name, description.

Sincronizar fontes de conhecimento​

Depois de adicionar ou atualizar arquivos em uma fonte de conhecimento baseada em arquivos (como um volume ou tabela do Unity Catalog), acione uma sincronização para atualizar o índice do assistente de conhecimento com o conteúdo mais recente do arquivo.

nota

As fontes de conhecimento baseadas em índice são atualizadas automaticamente e não exigem uma sincronização manual.

Python
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

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

Migrar um assistente de conhecimento entre workspace​

Você pode usar o SDK para replicar um assistente de conhecimento de um workspace para outro. O exemplo a seguir recupera um assistente de conhecimento do workspace de origem e o recria, juntamente com suas fontes de conhecimento, no workspace de destino.

nota

As fontes de conhecimento referenciadas no workspace de destino (como índices AI Search ou volumes Unity Catalog) já devem existir no workspace de destino antes de você criar as fontes de conhecimento.

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,
        ),
    )

Substitua os valores de espaço reservado pelos valores apropriados para seus workspaces de origem e de destino. O <source-knowledge-assistant-name> segue o formato knowledge-assistants/<knowledge-assistant-id>.

Avalie seu assistente de conhecimento​

Este Notebook demonstra como avaliar um Assistente de Conhecimento usando conjuntos de dados de avaliação selecionados e avaliadores personalizados.

Abrir notebook em uma nova aba

Limitações​

  • Arquivos maiores que 50 MB são ignorados automaticamente durante a ingestão e não são incluídos na base de conhecimento.
  • Arquivos PDF, DOC, DOCX, PPT e PPTX com mais de 500 páginas são ignorados durante a ingestão. Para arquivos do PowerPoint (PPT, PPTX), cada slide conta como uma página. Arquivos TXT e MD não têm limite de página. A ingestão usa ai_parse_document, que tem um limite de 500 páginas por documento.
  • Arquivos com nomes que começam com um sublinhado (_) ou ponto (.) são automaticamente ignorados durante a ingestão e não são incluídos na base de conhecimento.
  • Para fontes de conhecimento que usam arquivos de uma tabela do Unity Catalog, somente a coluna de conteúdo selecionada é ingerida. Outras colunas na fonte de conhecimento da tabela não são usadas.
  • Apenas índices de Pesquisa de AI que usam um dos seguintes modelos de embedding são suportados: databricks-gte-large-en, databricks-bge-large-en ou databricks-qwen3-embedding-0-6b.
Nesta página