Pregunta al Oráculo

Cómo funciona el asistente de IA en el sitio — RAG sobre los documentos, servido por tu propio Ollama en su Ollama.

Stable Reading time ~ 3 min Edit on GitHub

El botón amarillo en la esquina de cada página es el Oráculo Nibiru — un asistente de IA respaldado por esta documentación misma. Pregúntale sobre el enrutamiento, los módulos, la CLI, la capa Smarty, el significado de pageAction(). Cita sus fuentes.

¿Qué lo alimenta?

Por defecto, el Oracle se ejecuta completamente en su propia infraestructura:

Capa	Backend	Modelo predeterminado
Chat (generación de respuestas)	Ollama en `https://your-ollama-host.example`	`qwen2.5-coder:14b`
Embeddings (recuperación RAG)	Ollama en `https://your-ollama-host.example`	`nomic-embed-text`

No se utilizan claves de API pagas. Ningún dato sale de su red. El clúster de 5 GPU de Ollama que ya ejecuta maneja la carga.

Si prefieres utilizar un proveedor de pago — Claude para chat, OpenAI para embebidos — establece LLM_PROVIDER=anthropic y/o EMBED_PROVIDER=openai junto con las claves de API correspondientes. Las rutas de código son idénticas.

¿Cómo funciona

flowchart LR
  A[User question] --> B[Embed via Ollama<br/>nomic-embed-text]
  B --> C[Cosine search<br/>against pre-computed<br/>doc-chunk index]
  C --> D[Top-K chunks]
  D --> E[Ollama chat<br/>qwen2.5-coder:14b<br/>system + retrieved context]
  E --> F[Answer + source list]
  F --> G[Render in chat UI]

A la hora de la construcción, el sitio de documentación recorre cada página Markdown, la divide en fragmentos de aproximadamente 600 tokens en los límites H2/H3, incrusta cada fragmento con nomic-embed-text y escribe el resultado en public/oracle-index.json. No se necesita una base de datos.
A la hora de la solicitud, la pregunta del usuario se incrusta de la misma manera, los fragmentos más cercanos se recuperan por similitud coseno y se unen para formar un sistema de indicación para el modelo de chat.
El modelo de chat responde en el idioma del usuario, citando los fragmentos fuente por URL.

Archivos

Archivo	Propósito
`scripts/lib/providers.mjs`	Adaptador compartido de chat y embedding (Ollama / Anthropic / OpenAI).
`scripts/build-oracle-index.mjs`	Construye `public/oracle-index.json` en tiempo de compilación.
`public/oracle-index.json`	El índice de embedding comprometido/salida de la compilación.
`src/pages/api/oracle.ts`	El punto final SSR al que el widget de chat POSTea. También sirve un GET para diagnósticos.
`src/components/CosmicHeader.astro`	El lanzador flotante + interfaz de usuario de chat.

Configuración única en su Ollama.ai

Extraiga los dos modelos que usa Oracle:

curl https://your-ollama-host.example/api/pull -d '{"name":"qwen2.5-coder:14b"}'
curl https://your-ollama-host.example/api/pull -d '{"name":"nomic-embed-text"}'

qwen2.5-coder:14b ya está instalado (verificado en vivo). nomic-embed-text es la pieza faltante; sin ella, el Oracle funciona solo en modo de chat (sin RAG).

Configurando el sistema

El Oracle lee su configuración desde las variables de entorno. Se incluyen valores predeterminados sensibles.

# Default mode (Ollama on your Ollama instance)
LLM_PROVIDER=ollama                                 # default
OLLAMA_BASE_URL=https://your-ollama-host.example            # default
OLLAMA_CHAT_MODEL=qwen2.5-coder:14b                 # default
OLLAMA_EMBED_MODEL=nomic-embed-text                 # default

# Optional fallbacks
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-haiku-4-5-20251001

EMBED_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_EMBED_MODEL=text-embedding-3-small

# Behaviour
ORACLE_TOP_K=6
ORACLE_MAX_TOKENS=800

Punto final de diagnóstico

GET /api/oracle devuelve la configuración actual (sin secretos):

curl https://nibiru-framework.com/api/oracle
{
  "status": "ok",
  "llm":   { "provider": "ollama", "ollamaUrl": "https://your-ollama-host.example",
             "model": "qwen2.5-coder:14b" },
  "embed": { "provider": "ollama", "ollamaUrl": "https://your-ollama-host.example",
             "model": "nomic-embed-text" },
  "index": { "present": true, "chunks": 177,
             "provider": "ollama", "model": "nomic-embed-text" }
}

Útil para verificar que un contenedor recién desplegado esté utilizando el backend que esperabas.

Privacidad

Las preguntas y el historial de conversaciones se envían a su servidor Ollama. No se almacenan por el sitio de documentación ni por Anthropic/OpenAI en la configuración predeterminada de Ollama.
La clave OpenAI (si se utiliza) solo se invoca para los embeddings.
No se establecen análisis o cookies por parte del widget Oracle mismo.

¿Por qué un modelo entrenado en Nibiru?

El plan de desarrollo (ver Plan de IA) es afinar un LoRA en la exportación del Corpus de Entrenamiento para que el modelo de chat mismo sea nativo de Nibiru. Cuando esté listo, el OLLAMA_CHAT_MODEL del Oracle se cambia al modelo afinado y el sistema prompt se simplifica. Misma código, respuestas más inteligentes.

Pruébalo

Abre el Oracle (el planeta ámbar, en la parte inferior derecha) e intenta uno de estos:

“How do I create a new module?”
“What does pageAction do?”
“Show me how to handle a JSON endpoint.”
“Wie schreibe ich eine Migration?” (German works.)
“認証フローを教えて” (Japanese works.)