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

Esta página descreve como usar o Knowledge Assistant para criar um chatbot de perguntas e respostas sobre os seus documentos e melhorar a sua qualidade com base no feedback em linguagem natural dos seus especialistas na matéria.

O que é o Assistente de Conhecimento?

Use o Knowledge Assistant para criar um chatbot que possa responder a perguntas sobre os seus documentos e fornecer respostas de alta qualidade com citações. O Knowledge Assistant utiliza IA avançada e segue uma abordagem Instructed Retriever para resolver as limitações da abordagem tradicional de geração aumentada por recuperação (RAG) e fornecer as respostas da mais alta qualidade com base na documentação que fornece.

O Knowledge Assistant é ideal para suportar os seguintes casos de uso:

• Responda às perguntas dos utilizadores com base na documentação do produto.
• Responder a perguntas dos colaboradores relacionadas com as políticas de RH.
• Responda às perguntas dos clientes com base nas bases de conhecimento de suporte.

O Knowledge Assistant 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. Faça perguntas e orientações diretamente na experiência e partilhe o seu agente para que outros colaborem e melhorem o desempenho do agente.

O Knowledge Assistant cria um endpoint de agente que podes usar a jusante para as tuas aplicações. 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 o agente responderá com citações.

O Knowledge Assistant utiliza armazenamento padrão para armazenar transformações temporárias de dados, pontos de verificação de modelos e metadados internos que alimentam cada agente. Na exclusão do agente, todos os dados associados ao agente são removidos do armazenamento padrão.

Requirements

• Um espaço de trabalho que inclui o seguinte:
  • Computação sem servidor disponível (ativada por padrão em áreas de trabalho com o Unity Catalog numa região suportada).
  • Catálogo Unity ativado. Consulte Habilitar um espaço de trabalho para o Unity Catalog.
  • Acesso ao Mosaic AI Model Serving.
  • Acesso a uma política de orçamento sem servidor com um orçamento diferente de zero.
  • Monitoramento de produção para MLflow (Beta) habilitado. Isso é necessário para que o rastreamento funcione. Se não precisar de traçar, não precisa de ativar esta pré-visualização. Ver Gerir as pré-visualizações de Azure Databricks.
• Um espaço de trabalho numa das regiões suportadas.
• O endpoint do modelo de embedding deve ter guarda-corpos de IA e limites de velocidade desativados. Consulte Configurar o AI Gateway em pontos de extremidade de disponibilização de modelos.
• Você deve ter os dados de entrada prontos para uso. Pode optar por fornecer:
  • Arquivos num volume ou num diretório de volume do Catálogo Unity. Os tipos de ficheiros 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) Monitorização de produção para MLflow (Beta) ativada. Isso é necessário para que o rastreamento funcione. Ver Gerir as pré-visualizações de Azure Databricks.

Criar um agente assistente de conhecimento

Vá para o Agentes no painel de navegação esquerdo do seu espaço de trabalho. Clique em Criar Agente e selecione Assistente de Conhecimento.

Etapa 1: Configurar o agente

Configure o seu agente e forneça fontes de conhecimento para ele 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. Você pode optar por fornecer arquivos do Catálogo Unity ou um índice de pesquisa vetorial.

   Arquivos UC

   Para ficheiros UC, são suportados os seguintes tipos de ficheiros: txt, pdf, md, ppt/pptx e doc/docx. Os ficheiros com mais de 50 MB são automaticamente ignorados durante a ingestão e não serão incluídos na base de dados de conhecimento.

   1. Em Tipo, selecione Arquivos UC.
   2. No campo Origem , selecione o volume do Catálogo Unity 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 Descrever o conteúdo, descreva o conteúdo que a fonte de conhecimento contém para ajudar o agente a entender quando usar essa fonte de dados.

   Índice de pesquisa vetorial

   Note

   Os índices de pesquisa vetorial só são suportados se o índice for usado databricks-gte-large-en como modelo de incorporação. Ao criar seu índice de pesquisa vetorial, certifique-se de selecionar esse modelo de incorporação. Para obter mais informações, consulte Criar um índice de pesquisa vetorial.

   1. Em Tipo, selecione Índice de pesquisa vetorial.
   2. No campo Origem , selecione o índice de pesquisa vetorial que deseja fornecer ao agente.
   3. No campo Nome , insira um nome para sua fonte de conhecimento.
   4. Na coluna URI do documento, selecione a coluna com um link ou referência à origem das informações. 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 Descrever o conteúdo, descreva o conteúdo que a fonte de conhecimento contém para ajudar o agente a entender quando usar essa fonte de dados.

4. (Opcional) Se 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 diretrizes sobre como o agente deve responder.

6. Clique em Criar agente.

Pode levar até algumas horas para criar seu agente e sincronizar as fontes de conhecimento fornecidas. Quando o agente está pronto, o painel lateral direito mostra as fontes de conhecimento sincronizadas.

Etapa 2: Testar seu agente

Depois de o seu agente terminar de construir, teste-o conversando com ele. O agente deve responder com citações para questões relacionadas com as suas fontes de conhecimento.

1. Inicia a conversa diretamente com o seu agente no separador Build.
2. (Opcional) Também podes clicar em Abrir no Playground para conversar com ele no AI Playground.
3. Insira uma pergunta para o seu agente.
4. Avalie a sua resposta:
   1. Clique em Ver pensamentos para ver como o seu agente abordou a resposta à pergunta.
   2. Clique em Ver rastreio para ver o rastreio completo. Pode adicionar etiquetas aos rastros na interface do utilizador para acompanhar as avaliações de qualidade durante o processo de desenvolvimento.
   3. Clique em Ver fontes para ver que ficheiros o agente cita como referências. Isto abre um painel lateral com uma lista de fontes para rever.

Se estiver satisfeito com o desempenho do seu agente, continue a usá-lo tal como está.

Passo 3: Melhorar a qualidade

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

No separador Exemplos, adicione perguntas que os seus utilizadores farão ou perguntas que o seu agente já tenha respondido errado. Em alternativa, também pode importar dados rotulados diretamente de uma tabela do Unity Catalog.

1. Adicionar perguntas ao rótulo:

   1. Clique em + Adicionar para adicionar uma pergunta.
   2. Na modalidade 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 deseja avaliar.
   5. Para excluir uma pergunta, clique no menu kebab e, em seguida, clique em Excluir.

2. Depois de terminar de adicionar as suas perguntas, pode partilhar o agente com outros para rever e ajudar a construir um conjunto de dados rotulado de alta qualidade. No canto superior direito, clique no para gerir permissões.

   Para que os especialistas possam aceder e fornecer feedback, é necessário conceder-lhes as seguintes permissões:

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

3. Partilhe um link para a página de configuração do seu Assistente de Conhecimento para recolher feedback de especialistas.

4. Para rotular dados, clique numa pergunta e adicione Diretrizes no painel que aparece. As diretrizes aplicam-se logo após serem salvas.

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

(Opcional) Importação e exportação de dados rotulados

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

1. Clique em Importar.

2. No campo Origem , selecione a tabela Catálogo Unity que contém os dados rotulados.

   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 orientações são integradas na tabela de dados rotulada à direita.

Para exportar dados rotulados como uma tabela do Catálogo Unity:

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

É criada uma nova tabela com os dados rotulados.

Gerir fontes de conhecimento

Depois de criar um assistente de conhecimento, pode adicionar, remover e atualizar fontes de conhecimento sem recriar o agente. Só o criador do assistente de conhecimento pode gerir as fontes de conhecimento.

Pode rascunhar várias alterações ao mesmo tempo — por exemplo, adicionar uma nova fonte, remover uma existente e atualizar a descrição de outra — e depois aplicar todas as alterações simultaneamente ao clicar em Guardar e Atualizar.

Adicionar uma fonte de conhecimento

1. Na página de configuração do agente, vai ao separador Fontes .
2. Clique + Adicionar abaixo dos cartões de fonte de conhecimento existentes.
3. Selecione o tipo de fonte de conhecimento a adicionar (ficheiros do Catálogo Unity ou índice de pesquisa vetorial) e configure-o conforme descrito no Passo 1: Configure o seu agente.
4. Clique em Guardar e Atualizar.

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

Remover uma fonte de conhecimento

1. Na página de configuração do agente, vai ao separador Fontes .
2. Passe o rato sobre o cartão fonte de conhecimento que quer remover e clique no no canto superior direito.
3. No diálogo de confirmação, clique em Confirmar para remover a fonte.
4. Clique em Guardar e Atualizar.

A fonte de conhecimento e os seus dados associados são removidos do agente. Esta ação não é facilmente reversível porque voltar a adicionar a fonte requer reingerir os dados.

Atualizar detalhes da fonte do conhecimento

Pode atualizar o nome e a descrição de uma fonte de conhecimento existente. Estes detalhes ajudam o agente a perceber quando deve usar cada fonte.

1. Na página de configuração do agente, vai ao separador Fontes .
2. Passe o rato sobre o cartão fonte de conhecimento que quer editar e clique no ícone do lápis.
3. Atualize os campos Nome ou Descrição .
4. Clique em Guardar e Atualizar.

Gerenciar permissões

Por defeito, apenas os autores de agentes e os administradores de espaços de trabalho têm permissões sobre o agente. Para permitir que outros usuários editem ou consultem seu agente, você precisa conceder explicitamente a eles permissão.

Para gerenciar permissões em seu agente:

1. Abra o seu agente na página de Agentes.
2. Na parte superior, clique no
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 para conceder:
   • Pode Gerir: Permite gerir o agente, incluindo definir permissões, editar a configuração do agente e melhorar a sua qualidade.
   • Can Query: Permite consultar o endpoint do agente no AI Playground e através da API. Os utilizadores com apenas esta permissão não podem visualizar ou editar o agente na página de Agentes.
6. Clique em Adicionar.
7. Clique em Salvar.

Consultar o ponto de extremidade do agente

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

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

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

Gerir assistentes de conhecimento usando o SDK Databricks

Pode usar o SDK Databricks para Python para criar e gerir programaticamente assistentes de conhecimento e as suas fontes de conhecimento. Para obter a lista completa de operações de API disponíveis, consulte a referência da API dos Assistentes de Conhecimento.

Crie um assistente de conhecimento

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

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.

Gerir fontes de conhecimento

Pode adicionar, remover e atualizar fontes de conhecimento num assistente de conhecimento existente usando o SDK.

Adicionar uma fonte de conhecimento

O exemplo seguinte adiciona uma fonte de conhecimento dos ficheiros do Unity Catalog a um assistente de conhecimento já existente.

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 em vez disso, use IndexSpec:

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 seguinte elimina uma fonte de conhecimento de um assistente de conhecimento.

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 seguinte atualiza o nome de apresentação e a descrição de uma fonte de conhecimento existente.

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.

Migre um assistente de conhecimento entre espaços de trabalho

Pode usar o SDK para replicar um assistente de conhecimento de um espaço de trabalho para outro. O exemplo seguinte recupera um assistente de conhecimento do espaço de trabalho de origem e recria-o, juntamente com as suas fontes de conhecimento, no espaço de trabalho alvo.

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 provisórios pelos valores apropriados para os seus espaços de trabalho de origem e destino. O <source-knowledge-assistant-name> segue o formato knowledge-assistants/<knowledge-assistant-id>.

Avalie o seu assistente de conhecimento

Este bloco de anotações demonstra como avaliar um Databricks Knowledge Assistant usando conjuntos de dados de avaliação com curadoria e pontuadores personalizados.

Obter bloco de notas

Limitations

• Só o inglês é suportado.
• Os ficheiros com mais de 50 MB são automaticamente ignorados durante a ingestão e não são incluídos na base de dados de conhecimento.
• Ficheiros com nomes que começam por sublinhado (_) ou ponto (.) são automaticamente ignorados durante a ingestão e não são incluídos na base de conhecimento.
• As tabelas do Catálogo Unity não são suportadas.
• Somente índices de pesquisa vetorial que usam databricks-gte-large-en como modelo de incorporação são suportados.
• Limitações de IA e limitações de velocidade devem ser desativadas no endpoint databricks-gte-large-en do modelo. Consulte Configurar o AI Gateway em pontos de extremidade de disponibilização de modelos.
• Para que o rastreamento funcione, você deve habilitar o monitoramento de produção para MLflow (Beta). Se não precisar de traçar, não precisa de ativar esta pré-visualização. Ver Gerir as pré-visualizações de Azure Databricks.