Confira o Cookbook da nova API Gemini e nosso fórum da comunidade.

Esta página foi traduzida pela API Cloud Translation.

Crie uma pesquisa de conteúdo de IA com o agente do Documentos

A pesquisa de informações é um dos usos mais comuns de modelos generativos de inteligência artificial (IA). Criar uma interface de pesquisa conversacional para seu conteúdo usando IA permite que os usuários façam perguntas específicas e recebam respostas diretas.

Neste tutorial, mostramos como criar uma interface de pesquisa conversacional com tecnologia de IA para seu conteúdo. Ele é baseado no Docs Agent, um projeto de código aberto que usa a API Google Gemini para criar uma interface de pesquisa conversacional, sem treinar um novo modelo de IA ou fazer ajustes com os modelos do Genmini. Isso significa que é possível criar esse recurso de pesquisa rapidamente e usá-lo para conjuntos de conteúdo pequenos e grandes.

Para ter uma visão geral em vídeo do projeto e saber como estendê-lo, incluindo insights das pessoas que o criaram, confira: Pesquisa de conteúdo de IA | Desenvolver com a IA do Google. Caso contrário, comece a estender o projeto seguindo as instruções abaixo.

Visão geral

O projeto do agente do Documentos oferece uma interface de pesquisa conversacional para um conjunto de conteúdo específico, com suporte da API Google Gemini e de modelos generativos. Os usuários podem fazer uma pergunta detalhada em um estilo conversacional e receber uma resposta detalhada com base em um conjunto de conteúdo específico. Nos bastidores, o agente do Documentos usa a pergunta e pesquisa em um banco de dados de vetores do conteúdo, criando um comando detalhado para o modelo generativo, incluindo snippets de texto relevante. O modelo generativo gera uma resposta à pergunta, e o agente do Documentos a formata e a apresenta ao usuário.

Diagrama funcional do agente do Documentos Figura 1. Diagrama funcional do app de projeto do agente do Documentos.

A chave para que o agente do Documentos possa responder a perguntas sobre seu conteúdo é a criação de um banco de dados vetorial desse conteúdo. Você separa seu conteúdo em blocos lógicos de texto e gera um vetor para cada um deles. Esses vetores são representações numéricas das informações em cada bloco e são gerados com uma função de embedding de texto de IA dos modelos generativos do Google.

Quando um usuário faz uma pergunta, o agente do Documentos usa a mesma função de embedding de texto para criar uma representação numérica da pergunta e usa esse valor para pesquisar o banco de dados de vetores e encontrar conteúdo relacionado. Ele recebe os principais resultados e adiciona essas informações a um comando para o modelo generativo. O modelo de IA recebe a pergunta e as outras informações de contexto e gera uma resposta.

Configuração do projeto

Estas instruções ajudam você a configurar o projeto do agente do Documentos para desenvolvimento e teste. As etapas gerais são instalar um software de pré-requisito, definir algumas variáveis de ambiente, clonar o projeto do repositório de código e executar a instalação da configuração. O projeto de código usa poesia do Python para gerenciar pacotes e o ambiente de execução do Python.

Instale os pré-requisitos

O projeto do Agente do Docs usa Python 3 e poesia em Python para gerenciar pacotes e executar o aplicativo. As instruções de instalação a seguir são para uma máquina host do Linux.

Para instalar o software necessário:

Instale o Python 3 e o pacote de ambiente virtual venv para Python.
```
sudo apt update
sudo apt install git pip python3-venv
```
Instale o Python Poetry para gerenciar dependências e empacotamento do projeto.
```
curl -sSL https://install.python-poetry.org | python3 -
```

Use a poesia em Python para adicionar mais bibliotecas se ampliar o projeto.

Defina as variáveis de ambiente

Defina algumas variáveis de ambiente necessárias para permitir que o projeto do código do agente do Documentos seja executado, incluindo uma chave de API do Google Gemini e uma configuração de poesia em Python. Adicione essas variáveis ao arquivo $HOME/.bashrc se você estiver usando o Linux, a fim de torná-las padrão para as sessões do terminal.

Para definir as variáveis de ambiente:

Gere uma chave de API do Google Gemini e copie a string da chave.
Defina a chave de API como uma variável de ambiente. Em hosts do Linux, use o comando a seguir.
```
export API_KEY=<YOUR_API_KEY_HERE>
```
Resolva um problema conhecido (link em inglês) de poesia em Python definindo o parâmetro PYTHON_KEYRING_BACKEND. Em hosts do Linux, use o seguinte comando.
```
export PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring
```

Clonar e configurar o projeto

Faça o download do código do projeto e use o comando de instalação do Poetry para fazer o download das dependências necessárias e configurar o projeto. Você precisa do software de controle de origem git para recuperar o código-fonte do projeto. external Para fazer o download e configurar o código do projeto:

Clone o repositório git usando o comando a seguir.

git clone https://github.com/google/generative-ai-docs

Como opção, configure seu repositório git local para usar a finalização da compra esparsa, para que você tenha apenas os arquivos para o projeto do agente do Documentos.
```
cd generative-ai-docs/
git sparse-checkout init --cone
git sparse-checkout set examples/gemini/python/docs-agent/
```
Mova para o diretório raiz do projeto docs-agent.
```
cd examples/gemini/python/docs-agent/
```
Execute o comando de instalação "Poetry" para fazer o download de dependências e configurar o projeto:
```
poetry install
```

Preparar conteúdo

O projeto do agente do Documentos foi projetado para funcionar com conteúdo de texto e inclui ferramentas específicas para trabalhar com sites que usam Markdown como o formato de origem. Se você estiver trabalhando com conteúdo do site, preserve (ou replique) a estrutura de diretórios do site exibido para permitir que a tarefa de processamento de conteúdo mapeie e crie links para esse conteúdo.

Dependendo do formato e dos detalhes do conteúdo, pode ser necessário limpá-lo para remover informações não públicas, observações internas ou outras informações que você não quer que sejam pesquisáveis. Mantenha a formatação básica, como títulos e cabeçalhos, que ajudam a criar divisões lógicas de texto, ou pedaços, na etapa de processamento de conteúdo.

Para preparar o conteúdo para processamento:

Crie um diretório para o conteúdo que você quer que o agente de IA pesquise.
```
mkdir docs-agent/content/
```
Copie seu conteúdo para o diretório docs-agent/content/. Se o conteúdo for um site, preserve (ou replique) a estrutura de diretórios do site disponibilizado.
Limpe ou edite o conteúdo conforme necessário para remover informações não públicas ou outras informações que você não quer incluir nas pesquisas.

Usar documentos do Flutter para testes

Se você precisar de um conjunto de conteúdo para testar o agente do Documentos, use os documentos para desenvolvedores do Flutter.

Para acessar os documentos para desenvolvedores do Flutter:

Acesse o diretório de conteúdo para encontrar o conteúdo que você quer que o agente de IA pesquise.
```
cd docs-agent/content/
```

Clone os documentos do Flutter no diretório docs-agent/content/.

git clone --recurse-submodules https://github.com/flutter/website.git

Processar conteúdo

Para que o agente de pesquisa pesquise de maneira eficaz o conteúdo relacionado às perguntas dos usuários, é necessário criar um banco de dados de vetores que representem seu conteúdo. Os vetores são gerados usando uma função de modelo generativo de IA chamada embedding de texto. Embeddings de texto são representações numéricas do conteúdo de texto. Eles se aproximam do significado semântico do texto como um conjunto de números. Ter representações numéricas de informações permite que o sistema faça a pergunta de um usuário, aproxime o significado dela usando a mesma função de embedding de texto e, em seguida, encontre informações relacionadas como um cálculo matemático, usando um algoritmo de k-vizinhos mais próximos (k-NN).

Dividir conteúdo de texto

A quantidade de texto que um vetor de embedding de texto pode representar efetivamente é limitada. Esse projeto limita o texto representado em um vetor a 3.000 caracteres ou menos, e isso significa que você precisa dividir o conteúdo em partes dentro desse limite. Nesta seção, descrevemos como usar um script fornecido com o projeto do Docs Agent para dividir arquivos Markdown em blocos de texto menores. Para dicas sobre como trabalhar com outros formatos de conteúdo, consulte Processar outros formatos.

Para dividir o conteúdo do formato Markdown:

Configure os parâmetros de entrada para o script de processamento editando o arquivo docs-agent/config.yaml. Este exemplo é destinado a um subconjunto dos documentos do Flutter:
```
input:
- path: "content/website/src/ui"
  url_prefix: "https://docs.flutter.dev/ui"
```
Salve as mudanças neste arquivo de configuração.
Navegue até o diretório do projeto docs-agent:
```
cd docs-agent/
```
Divida o conteúdo de origem do Markdown executando o comando agent chunk:
```
agent chunk
```

O script processa o conteúdo de entrada e cria arquivos de texto de saída no diretório docs-agent/data, dividindo o texto com base em títulos, cabeçalhos e parágrafos relacionados. O processamento pode levar algum tempo, dependendo do tamanho do conteúdo.

Criar vetores de embedding de texto

Depois de dividir o conteúdo em partes significativas de tamanho adequado, é possível preencher o banco de dados de vetores com seu conteúdo usando uma função de incorporação de texto. O projeto do agente do Documentos usa o banco de dados de vetores Chroma para armazenar vetores de embedding de texto. Estas instruções abordam como usar o script dos agentes do Documentos para preencher um banco de dados de vetores com o conteúdo dividido.

Para gerar embeddings de texto e preencher o banco de dados de vetores:

Navegue até o diretório do projeto docs-agent:
```
cd docs-agent/
```
Preencha o banco de dados de vetores com seu conteúdo usando o comando agent populate:
```
agent populate
```

Esse script usa a API Google Gemini para gerar vetores de embedding de texto e, em seguida, salva a saída no banco de dados de vetores. O processamento pode levar algum tempo, dependendo do tamanho do conteúdo.

Processar outros formatos

O projeto do agente de documentos foi projetado para funcionar com o conteúdo de sites no formato Markdown. Os autores do projeto criaram alguns scripts de conversor para gerar outros tipos de conteúdo no formato Markdown, incluindo Documentos Google, Portable Document Format (PDF) e Gmail. Para mais informações sobre como usar esses conversores, consulte o diretório docs-agent/apps_script do repositório de código.

Converter outros formatos de conteúdo

É possível usar outros formatos de conteúdo com o projeto, mas esses métodos extras precisam ser criados por você ou outros membros da comunidade. Confira o repositório de códigos Problemas e Solicitações de envio para que as pessoas criem soluções semelhantes.

O código-chave que você precisa criar para oferecer suporte a outros formatos de conteúdo é um script divisor, como o script files_to_plain_text.py. Tente criar um script ou programa que gere uma saída semelhante a este. A saída de texto final precisa ter formatação mínima e informações irrelevantes. Se você estiver usando formatos de conteúdo como HTML ou JSON, remova o máximo possível da formatação não informativa (tags, scripts, CSS), para que ela não distorça os valores dos embeddings de texto gerados a partir deles.

Depois de criar um script de divisor para o formato de conteúdo, será possível executar o script populate_vector_database.py para preencher o banco de dados de vetores. Para mais informações sobre o processamento de arquivos para usar com o Agente de documentos, consulte o Leiame de pré-processamento do Agente de Documentos.

Testar o app

Quando terminar de preencher o banco de dados de vetores, o projeto estará pronto para teste. O projeto fornece uma função de empacotamento para executá-lo localmente.

Para executar e testar a interface da Web do projeto:

Navegue até o diretório do projeto docs-agent:
```
cd docs-agent/
```
Execute o script de inicialização do aplicativo da Web:
```
agent chatbot
```
Usando um navegador da Web, acesse o endereço da Web do URL mostrado na saída do script de inicialização e teste o aplicativo.
```
* Running on http://your-hostname-here:5000
```

Opções de implementação

A API Gemini fornece ferramentas de programação que podem substituir componentes da implementação do agente do Documentos, especificamente: recuperação semântica e variante de modelo de resposta a perguntas atribuídas (AQA, na sigla em inglês). Use o recurso Recuperação semântica da API Gemini para substituir o banco de dados de vetores separado. O recurso de recuperação semântica permite gerar embeddings para seu conteúdo e o armazenar. O modelo AQA do Gemini é ajustado para responder perguntas com material de origem fornecido em um comando. Use a recuperação semântica com o modelo AQA para responder perguntas sobre seu conteúdo na API Gemini.

O agente do Documentos inclui opções de configuração para usar o recurso da API de recuperação semântica, esse modelo do AQA Gemini ou ambos. Para mais informações, consulte o arquivo README do agente do Documentos.

Outros recursos

Para mais informações sobre o projeto do agente do Documentos, consulte o repositório de códigos. Se você precisar de ajuda para criar o aplicativo ou estiver procurando colaboradores desenvolvedores, confira o servidor da Comunidade de desenvolvedores do Google no Discord.

Aplicativos de produção

Se você planeja implantar o agente do Docs para um público grande, observe que o uso da API Google Gemini pode estar sujeito a limitação de taxa e outras restrições de uso. Se estiver pensando em criar um aplicativo de produção com a API Gemini, como o Docs Agent, confira os serviços da Vertex AI do Google Cloud para aumentar a escalonabilidade e a confiabilidade do seu app.