Saltar para o conteúdo principal
Versão: 2.0.0

developer-docs-ai-agent

Normalmente, os agentes de IA são considerados como alguns bots que podem fazer coisas e um pouco inteligentes. Mas, na prática, os agentes de desenvolvimento mais úteis são agentes especializados super-focados com conhecimento privado e altamente curado. Por exemplo: os documentos oficiais de uma linguagem de programação ou talvez a referência interna da API de um protocolo/empresa.

O Gaia fornece as três peças que permitem a qualquer pessoa criar um agente especializado deste tipo sem grande complexidade. Uma base de conhecimentos que pode ser conectada e da qual se podem extrair fragmentos, uma pilha de conversação com reconhecimento de RAG que fala o estilo OPENAI v1/chat/completions e avisos de sistema modulares.

Um agente de documentação da linguagem de contrato inteligente Vyper​

Vamos em frente e criar um agente para a linguagem de contrato inteligente Vyper (uma alternativa ao Solidity com sabor a Python). Tudo o que você vê aqui - layout de diretório, comandos de embedding, flags de configuração de nós - traduz de 1 para 1 para qualquer outro conjunto de documentos: capítulos de livros de Rust, documentos da API REST do Django, um arquivo RFC ou qualquer documento.

Certifique-se de que tem o seu docker a funcionar e o vetor qdrant instalado executando docker pull qdrant/qdrant

Pré-requisitos: Ferramentas instaladas uma vez​

Tempo de execução WasmEdge - O utilitário de incorporação de Gaia é fornecido como um módulo WebAssembly leve; WasmEdge é o motor de execução que o executa nativamente em Linux/macOS/Windows:

curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install_v2.sh | bash -s

Por que Wasm? Porque obtém um artefacto de construção (um único ficheiro .wasm) que nunca precisa de ser instalado pelo pip. As equipas de segurança adoram o binário determinístico; o DevOps adora a história da dependência zero.

Incorporar pesos do modelo - O modelo que produz os seus vectores de frases de 768 dimensões vive no Hugging Face:

curl -LO https://huggingface.co/gaianet/Nomic-embed-text-v1.5-Embedding-GGUF/resolve/main/nomic-embed-text-v1.5.f16.gguf

Estes pesos estão no formato GGUF, o sucessor moderno do GGML, que transmite eficientemente a partir do disco e suporta variantes quantizadas para caixas apenas com CPU.

Vamos criar duas pastas como qdrant_storage e instantâneos do qdrant . Encontraremos a nossa base de conhecimentos instantânea no interior instantâneos do qdrant.

mkdir qdrant_storage
mkdir qdrant_snapshots

nohup docker run -d -p 6333:6333 -p 6334:6334 \
    -v $(pwd)/qdrant_storage:/qdrant/storage:z \
    -v $(pwd)/qdrant_snapshots:/qdrant/snapshots:z \
    qdrant/qdrant

Algumas notas de boas práticas:

  • Mapeie 6333 (REST/JSON) e 6334 (gRPC) se pensa que alguma vez fará uploads em massa ou executará benchmarks com os clientes Rust/Go Qdrant.
  • Persistir o qdrant_storage num volume montado significa que os seus vectores sobrevivem a um reinício do contentor e podem ser tar-gz'd para snapshots mais tarde.

Criar a coleção​

Começamos de novo porque a coleção de amostras predefinida do Gaia utiliza um tamanho de dimensão diferente.

Vamos remover se temos dados:

# Limpar quaisquer dados obsoletos
curl -X APAGAR 'http://localhost:6333/collections/default'

Em seguida, execute o seguinte.


# Provision a 768-dimensional, cosine-distance space
curl -X PUT 'http://localhost:6333/collections/default' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "vectors": {
      "size": 768,
      "distance": "Cosine",
      "on_disk": true
    }
  }'

A opção on_disk é sua amiga quando o corpus cresce para centenas de milhares de pedaços; o Qdrant mapeia os vectores em memória e deixa a RAM para o seu LLM.

Produzindo os Embeddings​

Vamos pegar a CLI de incorporação

curl -LO https://github.com/GaiaNet-AI/embedding-tools/raw/main/csv_embed/csv_embed.wasm

Prepare a sua documentação como​

Porquê CSV em vez de Markdown?  Achei mais fácil utilizar CSV do que markdown e é melhor se colares cada parte em colunas diferentes e uma célula por coluna. Não hesite em utilizar llm_info.txt se for essa a sua preferência.

Eu usei o gitingest para transformar o repositório git de documentos do vyper em um simples resumo de texto de sua base de código, o que é realmente útil para alimentar uma base de código/documentos no LLM.

Gerar os vectores​

Vamos certificar-nos de que o ficheiro csv/o ficheiro llm_info.txt se encontra no mesmo diretório e vamos gerar os vectores.

wasmedge --dir .:. \
  --nn-preload embedding:GGML:AUTO:nomic-embed-text-v1.5.f16.gguf \
  csv_embed.wasm embedding default 768 seus_docs.csv --ctx_size 8192
  • Repartição das bandeiras:
    • -dir .:. dá ao wasm sandbox leitura/escrita no diretório de trabalho, para que ele possa transmitir o CSV e escrever vetores de volta para o Qdrant.
    • -nn-preload embedding:GGML:AUTO:... pré-carrega o modelo uma vez, economizando ~2 s por 1.000 pedaços.
    • ctx_size é a janela de token secundária utilizada no modelo de incorporação, não no modelo de chat; aumente-a se os parágrafos do seu documento forem longos e vir truncamentos nos registos.

Pode executar o comando várias vezes com --start_vector_id para anexar novos fragmentos sem colisões; os Qdrant IDs são inteiros, por isso escolha um offset como 100_000 se planeia actualizações trimestrais de documentos.

Empacotamento e distribuição da base de conhecimentos​

Um snapshot nada mais é do que um diretório de arquivos JSON e Parquet que o Qdrant pode restaurar atomicamente. A compressão geralmente dá um ganho de tamanho de 3 para 1 porque os vetores são altamente repetitivos.

curl -X POST 'http://localhost:6333/collections/default/snapshots'

Agora é altura de comprimir os instantâneos, vamos até qdrant_snapshots/default e, em seguida, comprimi-lo através da execução.

tar czvf meu.instantâneo.tar.gz meu.snapshot

Em vez de my.snapshot basta usar o nome do ficheiro. Carregue o ficheiro my.snapshot.tar.gz para o huggingface, é necessário ter uma conta lá. Agora clique em new dataset (novo conjunto de dados) e carregue a sua base de conhecimentos.

Algumas práticas recomendadas (aprendidas da maneira mais difícil)​

  1. Estratégia de fragmentação

    O objetivo é ter 200-500 tokens por vetor. Se for demasiado curto, o índice é inundado com milhares de embeddings quase idênticos (ruído). Demasiado longo e o passo de recuperação devolve blocos que o modelo nunca lê completamente.

  2. Engenharia de sistemas rápidos

    Capacidades de frase e barreiras de proteção. Exemplo:

    "És um assistente linguístico Vyper. Se lhe fizerem perguntas que não sejam Vyper, recuse-as educadamente com um pedido de desculpas de uma só frase. Cite os números das linhas de código em todas as respostas."

  3. Ciclo de avaliação contínua

    Transfira as consultas dos utilizadores reais para uma folha de cálculo, classifique-as à mão como "Útil/Não Útil" e procure padrões: as pessoas pedem mais práticas recomendadas de segurança do que sintaxe? Isso diz-lhe que secções do documento precisam de exemplos mais ricos.

Depois de carregar a base de conhecimento no huggingface, é hora de mudar a base de conhecimento para o nosso llm. Se você ainda não teve a oportunidade de rodar seu próprio nó, você pode ir até aqui e começar.

Se quisermos selecionar um nó específico, vamos até aqui e escolhemos um LLM que funcione para mim.

Após a instalação, será necessário executar o seguinte:

gaianet config \
  --snapshot https://cara de abraço.co/conjuntos de dados/miau-ai/vyper-lang/resolver/principal/padrão-845259036638694-2025-04-22-09-28-18.instantâneo.tar.gz \
  --sistema-aviso "És um útil instrutor de vyper lang, por favor responde às perguntas"

Aqui --snapshot https://huggingface.co/... é o link para descarregar a minha base de conhecimentos que carreguei no huggingface.

Verá algo como o seguinte no seu terminal:


[+] Atualização o prompt do sistema do modelo de chat ...
    * Antigo prompt do sistema: Tu é um instrutor vyper lang útil, por favor, responda às perguntas
    * Novo prompt do sistema: Tu é um instrutor web3 útil, por favor, responda às perguntas

[+] Atualização o url do instantâneo ...
    * antigo url: https://cara de abraço.co/conjuntos de dados/miau-ai/web3-conhecimento-base/resolver/principal/padrão-8461598741381726-2025-04-29-07-50-41.instantâneo.tar.gz
    * Novo url: https://cara de abraço.co/conjuntos de dados/miau-ai/vyper-lang/resolver/principal/padrão-845259036638694-2025-04-22-09-28-18.instantâneo.tar.gz

✅ CONCLUÍDO! A configuração.json é atualizado com sucesso.

Agora deves ir em frente e iniciar o nó gaia usando início da gaianet.

Agora, o nó usará a base de conhecimento do vyper que acabamos de atualizar. Criámos com sucesso o nosso agente de documentação.