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

Esta página descreve como usar o Knowledge Assistant 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?

Utilize o Knowledge Assistant para criar um chatbot capaz de responder a perguntas sobre seus documentos e fornecer respostas de alta qualidade com citações. O Knowledge Assistant utiliza AI avançada e segue uma abordagem de Recuperação Instruída para superar as limitações da abordagem tradicional de geração aumentada por recuperação (RAG) e fornecer respostas da mais alta qualidade com base na documentação fornecida.

O Knowledge Assistant é ideal para dar suporte aos seguintes casos de uso:

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

O Assistente de Conhecimento permite que você melhore a qualidade do agente de chat e ajuste seu comportamento com base no feedback em linguagem natural de seus especialistas no assunto. Forneça perguntas e orientações 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 você pode usar posteriormente em seus aplicativos. Por exemplo, a imagem abaixo mostra como você pode interagir com o endpoint conversando com ele no AI Playground. Faça perguntas ao agente relacionadas aos seus documentos, e ele responderá com citações.

O Knowledge Assistant usa o armazenamentodefault para guardar transformações de dados temporárias, pontos de verificação de modelos e metadados internos que alimentam cada agente. Ao excluir um agente, todos os dados associados a ele são removidos do armazenamento default .

Requisitos

• Um workspace que inclui o seguinte:

  • computesem servidor disponível (ativada por default no espaço de trabalho com Unity Catalog).
  • Unity Catalog habilitado. Consulte Ativar um workspace para Unity Catalog.
  • Acesso ao Mosaic AI Model Serving.
  • Acesso a uma política orçamentáriaserverless com um orçamento diferente de zero.

• Um workspace em uma das regiões suportadas.

• O endpoint do modelo de incorporação databricks-gte-large-en deve ter os Guardrails AI e os limites de taxa desabilitados. Consulte Configurar AI Gateway no endpoint do modelo de operação.

• Você deve ter os dados de entrada prontos para uso. Você pode optar por fornecer:

  • Arquivos em um volume ou diretório de volume do Unity Catalog. Os tipos de arquivo suportados são txt, pdf, md, ppt/pptx e doc/docx.
  • Um índice de pesquisa vetorial que usa databricks-gte-large-en como modelo de incorporação. Consulte Criar um índice de pesquisa vetorial.

• (Opcional) Monitoramento de produção para MLflow (Beta) ativado. Isso é necessário para que o rastreamento funcione. Veja as prévias do Gerenciador Databricks.

Crie um agente assistente de conhecimento

Vá para Agentes no painel de navegação à esquerda do seu workspace. No bloco Assistente de Conhecimento , clique em Criar .

Etapa 1: configurar seu agente

Na tab "Construir" , configure seu agente e forneça as fontes de conhecimento para que ele possa usar ao responder às 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 do Unity Catalog ou um índice de pesquisa de vetores.

UC Files

Para arquivos UC, os seguintes tipos de arquivo são suportados: txt, pdf, md, ppt/pptx e doc/docx. Arquivos maiores que 50 MB são automaticamente ignorados durante a ingestão e não serão incluídos na base de conhecimento.

1. Em Tipo , selecione Arquivos UC .
2. No campo Source (Origem ), selecione o volume ou diretório do volume do Unity Catalog 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 da fonte de conhecimento para auxiliar o agente a compreender quando utilizar esta fonte de dados.

Vector Search Index

nota

Vector search indexes are only supported if the index uses databricks-gte-large-en as its embedding model. When creating your vector search index, ensure you select this embedding model. For more information, see Create a vector search index.

1. Em Tipo , selecione Índice de pesquisa vetorial .
2. No campo Fonte , selecione o índice de pesquisa vetorial que você deseja fornecer ao agente.
3. No campo Nome , insira um nome para sua fonte de conhecimento.
4. Na coluna Doc URI , selecione a coluna com um link ou referência de onde a informação veio. O agente usará isso em suas citações.
5. No campo Coluna de texto , especifique a coluna que contém o texto bruto que você deseja que o agente recupere.
6. Em Descreva o conteúdo , descreva o conteúdo da fonte de conhecimento para auxiliar o agente a compreender quando utilizar esta fonte de dados.

4. (Opcional) Se você quiser adicionar mais fontes de conhecimento, clique em Adicionar fonte de conhecimento . Você pode fornecer até 10 fontes de conhecimento.

5. (Opcional) No campo Instruções , especifique as diretrizes de como o agente deve responder.

6. Clique em Criar agente .

A criação do seu agente e a sincronização das fontes de conhecimento que você forneceu podem levar algumas horas. Quando o agente estiver pronto, o painel lateral direito exibirá as fontes de conhecimento sincronizadas.

importante

Se você atualizar ou adicionar arquivos às suas fontes de conhecimento, clique em Sincronize para que o agente detecte as alterações. A sincronização é feita de forma incremental. Por exemplo, se você adicionar um novo arquivo a um volume Unity Catalog previamente sincronizado, a sincronização processará apenas o arquivo recém-adicionado.

Somente o criador do assistente de conhecimento pode sincronizar as fontes de conhecimento.

Etapa 2: teste seu agente

Após a conclusão da criação do seu agente, 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 Criar .
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 visualizar pensamentos para ver como seu agente abordou a resposta à pergunta.
   2. Clique em "Ver rastreamento" para visualizar o rastreamento completo. Você pode adicionar rótulos aos rastreamentos na interface do usuário para acompanhar as avaliações de qualidade durante o processo de desenvolvimento.
   3. Clique em " Exibir 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 os serviços dele normalmente.

Etapa 3: melhorar a qualidade

O Assistente de Conhecimento pode ajustar o comportamento do agente com base no feedback em linguagem natural. Obtenha feedback de especialistas através da página de configuração para melhorar a qualidade do seu agente. Coletar dados de rótulos para seu agente pode melhorar sua qualidade e comportamento.

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

1. Adicionar perguntas ao 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é adicionar todas as perguntas que você deseja avaliar.
   5. Para excluir uma pergunta, clique no menu kebab e depois em Excluir.

2. Depois de adicionar suas perguntas, você pode compartilhar o agente com outras pessoas para que elas revisem e ajudem a criar um dataset de rótulos de alta qualidade. No canto superior direito, clique no menu de kebabs. para gerenciar permissões.

   Para que os especialistas possam acessar e fornecer feedback, você precisa conceder a eles as seguintes permissões:

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

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

4. Para etiquetar os dados, clique em uma pergunta e adicione as diretrizes no painel que aparece. As diretrizes entram em vigor imediatamente após serem salvas.

5. Teste o agente novamente na página de configuração ou no AI Playground para verificar seu desempenho aprimorado. Se necessário, adicione mais perguntas e orientações para continuar a melhorar o comportamento.

(Opcional) Importar e exportar dados de rótulos

Para importar novas perguntas e comentários diretamente de uma tabela do Unity Catalog:

1. Clique em Importar .

2. No campo Source (Fonte ), selecione a tabela Unity Catalog que contém os dados do 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 foram incorporadas à tabela de dados de rótulos à direita.

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

1. Clique em Exportar .
2. No campo Schema (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 do rótulo.

gerenciar fontes de conhecimento

Após criar um assistente de conhecimento, você pode adicionar, remover e atualizar fontes de conhecimento sem precisar recriar o agente. Somente o criador do assistente de conhecimento pode gerenciar as fontes de conhecimento.

Você pode fazer várias alterações de uma só vez — por exemplo, adicionar uma nova fonte, remover uma existente e atualizar a descrição de outra — e, em seguida, 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, acesse a tab Fontes .
2. Clique em + Adicionar abaixo dos cartões de fontes de conhecimento existentes.
3. Selecione o tipo de fonte de conhecimento a adicionar (arquivos Unity Catalog ou índice de pesquisa vetorial) e configure-a conforme descrito na etapa 1: Configure seu agente.
4. Clique em Salvar e Atualizar .

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

nota

Você pode fornecer até 10 fontes de conhecimento por assistente de conhecimento. Adicionar uma fonte de arquivos inicia um trabalho 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, acesse a tab Fontes .
2. Posicione o cursor sobre o cartão da fonte de conhecimento que deseja remover e clique no ícone da lixeira. no canto superior direito.
3. Na caixa de diálogo de confirmação, clique em Confirmar para remover a fonte.
4. Clique em Salvar e Atualizar .

A fonte de conhecimento e os dados associados são removidos do agente. Essa ação não é facilmente reversível, pois adicionar a fonte novamente 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 recurso.

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

gerenciar permissões

Por default, somente os autores do agente e os administradores workspace têm permissões para acessar o agente. Para permitir que outros usuários editem ou consultem seu agente, você precisa conceder-lhes permissão explicitamente.

Para gerenciar as permissões do seu agente:

1. Acesse o perfil do seu agente na página de Agentes .

2. Na parte superior, clique em Cardápio de kebabs.

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 que deseja conceder:

   • Gerenciar : Permite gerenciar o agente, incluindo definir permissões, editar a configuração do agente e melhorar sua qualidade.
   • Pode consultar : Permite consultar o endpoint do agente no AI Playground e por meio da API. Usuários com apenas essa 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 sincronizar e gerenciar fontes de conhecimento, incluindo adicionar, remover e atualizar fontes.

Consultar o agente endpoint

Na página do agente, clique Consulte o status do agente no canto superior direito para obter o endpoint do agente implantado e visualizar os detalhes do endpoint.

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

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

Gerencie assistentes de conhecimento usando o SDK Databricks

Você pode usar o SDK do Databricks para Python para criar e gerenciar assistentes de conhecimento e suas fontes de conhecimento de forma programática. Para obter a lista completa das operações de API disponíveis, consulte a referência da API dos Assistentes de Conhecimento.

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 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 vetorial, 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.

Migrar um assistente de conhecimento entre espaços de trabalho

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 de pesquisa vetorial 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 (
    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)

Substitua os valores de espaço reservado pelos valores apropriados para seu espaço de trabalho de origem e 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 Databricks Knowledge Assistant usando um conjunto de dados de avaliação selecionado e pontuadores personalizados.

Abrir notebook em uma nova aba

Limitações

• Apenas o inglês é suportado.

• 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 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.

• Não há suporte para as tabelas do Unity Catalog.

• Somente índices de pesquisa vetorial que usam databricks-gte-large-en como modelo de incorporação são suportados.

• Os guardrails e limites de taxa AI devem ser desabilitados no endpoint do modelo databricks-gte-large-en . Consulte Configurar AI Gateway no endpoint do modelo de operação.

• Para que o rastreamento funcione, você precisa habilitar o monitoramento de produção para o MLflow (Beta). Se você não precisa do rastreamento, não precisa ativar esta pré-visualização. Veja as prévias do Gerenciador Databricks.