Ir al contenido principal
Versión: 2.0.0

desarrollador-docs-ai-agent

Normalmente los agentes de IA son considerados como algunos bots que pueden hacer cosas y un poco inteligentes. Pero en la práctica, la mayoría de los agentes desarrolladores útiles son agentes especializados superenfocados con conocimiento privado y altamente curado. Por ejemplo: la documentación oficial de un lenguaje de programación o quizás la referencia de la API interna de un protocolo/empresa.

Gaia proporciona las tres piezas que permiten a cualquiera crear un agente especializado de este tipo sin mucha complejidad. Una base de conocimiento conectable en la que se pueden soltar trozos, una pila de chat compatible con RAG que habla el estilo OPENAI v1/chat/completions y avisos de sistema modulares.

Un agente de documentación del lenguaje de contratos inteligentes Vyper​

Vamos a crear un agente para el lenguaje de contratos inteligentes Vyper (una alternativa a Solidity con sabor a Python). Todo lo que ves aquí-disposición de directorios, comandos de incrustación, banderas de configuración de nodos-traduce 1-a-1 a cualquier otro conjunto de documentos: capítulos de libros de Rust, documentos de la API REST de Django, un archivo RFC o cualquier documento.

Asegúrate de que tienes tu docker funcionando y vector qdrant instalado ejecutando docker pull qdrant/qdrant

Requisitos previos: Herramientas que se instalan una vez​

WasmEdge Runtime - La utilidad de incrustación de Gaia se entrega como un módulo WebAssembly ligero; WasmEdge es el motor de ejecución que lo ejecuta de forma nativa en Linux/macOS/Windows:

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

¿Por qué Wasm? Porque se obtiene un artefacto de compilación (un único archivo .wasm) que nunca necesita la instalación de pip. A los equipos de seguridad les encanta el binario determinista; a DevOps le encanta la historia de la dependencia cero.

Incrustación de pesos del modelo - El modelo que produce sus vectores de frases de 768 dimensiones vive en Hugging Face:

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

Estos pesos están en el formato GGUF, el sucesor moderno de GGML, que se transmite eficientemente desde el disco y admite variantes cuantificadas para las cajas de sólo CPU.

Vamos a crear dos carpetas como qdrant_storage y qdrant_snapshots . Encontraremos nuestra base de conocimientos instantánea dentro de qdrant_snapshots.

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

Un par de notas sobre buenas prácticas:

  • Mapa 6333 (REST/JSON) y 6334 (gRPC) si crees que alguna vez vas a escribir cargas masivas o ejecutar benchmarks con los clientes Rust/Go Qdrant.
  • Persistir qdrant_storage en un volumen montado significa que tus vectores sobreviven a un reinicio del contenedor y pueden ser tar-gz'd para instantáneas más tarde.

Crear la colección​

Empezamos de cero porque la colección de muestras por defecto de Gaia utiliza un tamaño de dimensión diferente.

Quitemos si tenemos datos:

# Borrar los datos obsoletos
curl -X DELETE 'http://localhost:6333/collections/default'

Y luego ejecuta lo siguiente.


# 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
    }
  }'

La bandera on_disk es tu amiga cuando el corpus crece en cientos de miles de trozos; Qdrant mapea en memoria los vectores y deja RAM para tu LLM.

Producción de incrustaciones​

Agarremos la CLI de incrustación

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

Prepare su documentación como​

¿Por qué CSV en lugar de Markdown?  Me pareció más fácil usar CSV que markdown y es mejor si pegas cada trozo en columnas diferentes y una celda por columna. No dude en utilizar llm_info.txt si así lo prefiere.

He utilizado gitingest para convertir el repositorio git de vyper docs en un simple resumen de texto de su código base, lo que es realmente útil para alimentar un código base/documentos en LLM.

Generar los vectores​

Asegurémonos de que el archivo csv/el archivo llm_info.txt están en el mismo directorio y generemos los vectores.

wasmedge --dir .:. \
  --nn-preload embedding:GGML:AUTO:nomic-embed-text-v1.5.f16.gguf \
  csv_embed.wasm incrustación por defecto 768 tus_documentos.csv --ctx_size 8192
  • Desglose de banderas:
    • -dir .:. le da al sandbox wasm lectura/escritura en el directorio de trabajo, para que pueda transmitir el CSV y escribir vectores de vuelta a Qdrant.
    • -nn-preload embedding:GGML:AUTO:... precarga el modelo una vez, ahorrando ~2 s por cada 1.000 trozos.
    • ctx_size es la ventana de token secundaria utilizada en el modelo de incrustación, no en el modelo de chat; auméntala si los párrafos de tu documento son largos y ves truncamientos en los registros.

Puede ejecutar el comando varias veces con --start_vector_id para añadir nuevos fragmentos sin colisiones; los ID de Qdrant son números enteros, así que elija un desplazamiento como 100_000 si planea actualizaciones de documentos trimestrales.

Empaquetar y distribuir su base de conocimientos​

Una instantánea no es más que un directorio de archivos JSON y Parquet que Qdrant puede restaurar atómicamente. Comprimirla suele dar una ganancia de tamaño de 3 a 1 porque los vectores son muy repetitivos.

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

Ahora es el momento de comprimir las instantáneas, dirijámonos a qdrant_snapshots/default y luego comprimirlo ejecutándolo.

tar czvf mi.instantánea.tar.gz mi.snapshot

En lugar de mi.instantánea sólo tiene que utilizar el nombre del archivo. Sube mi.snapshot.tar.gz a huggingface, necesitarás tener una cuenta allí. Ahora haga clic en nuevo conjunto de datos y subir su base de conocimientos allí.

Algunas buenas prácticas (aprendidas por las malas)​

  1. Estrategia de fragmentación

    El objetivo es 200-500 tokens por vector. Si es demasiado corto, inundará el índice con miles de incrustaciones casi idénticas (ruido). Demasiado largo y el paso de recuperación devuelve bloques dispersos que el modelo nunca lee completamente.

  2. Ingeniería de sistemas

    Frase capacidades y guardarraíles. Ejemplo:

    "Eres un asistente lingüístico Vyper. Si le hacen preguntas que no sean de Vyper, rechácelas educadamente con una disculpa de una sola frase. Cite números de línea de código en cada respuesta".

  3. Bucle de evaluación continua

    Introduce consultas reales de los usuarios en una hoja de cálculo, etiquétalas a mano como "Útil/No útil" y busca patrones: ¿la gente pregunta más por las buenas prácticas de seguridad que por la sintaxis? Así sabrás qué secciones de la documentación necesitan ejemplos más detallados.

Después de cargar la base de conocimientos en huggingface, es hora de cambiar la base de conocimientos para nuestro llm. Si aún no has tenido la oportunidad de ejecutar tu propio nodo puedes dirigirte aquí y empezar.

Si queremos sol un nodo específico, así que vamos a la cabeza aquí y elegir un LLM que funciona para mí.

Después de la instalación tendremos que ejecutar lo siguiente:

gaianet config \
  --instantánea https://huggingface.co/conjuntos de datos/miau-ai/vyper-lang/resolver/principal/por defecto-845259036638694-2025-04-22-09-28-18.instantánea.tar.gz \
  --sistema-preguntar "Usted es un instructor vyper lang útil, por favor, responda a las preguntas"

Por aquí --snapshot https://huggingface.co/... es el enlace de descarga de mi base de conocimientos que he subido a huggingface.

Verás algo como lo siguiente en tu terminal:


[+] Actualización de el indicador del sistema de modelo de chat ...
    * Antiguo sistema prompt: Usted es un útil instructor de vyper lang, por favor responda a las preguntas
    * Nuevo sistema: Usted es un útil instructor web3, por favor responda a las preguntas

[+] Actualización de la url de instantánea ...
    * Antiguo url: https://huggingface.co/conjuntos de datos/miau-ai/web3-conocimiento-base/resolver/principal/por defecto-8461598741381726-2025-04-29-07-50-41.instantánea.tar.gz
    * Nuevo url: https://huggingface.co/conjuntos de datos/miau-ai/vyper-lang/resolver/principal/por defecto-845259036638694-2025-04-22-09-28-18.instantánea.tar.gz

✅ COMPLETADO¡! La página config.json se actualiza correctamente.

Ahora usted debe seguir adelante e iniciar el nodo gaia utilizando inicio de gaianet.

Ahora el nodo utilizará la base de conocimiento de vyper que acabamos de actualizar. Hemos creado con éxito nuestro agente de documentación.