Frage die Oracle

Wie der eingebettete KI-Assistent funktioniert – RAG über die Dokumentationen, bereitgestellt durch Ihren eigenen Ollama auf Ihrer Ollama-Instanz.

Stable Reading time ~ 3 min Edit on GitHub

Die orange Schaltfläche in der Ecke jeder Seite ist der Nibiru Oracle – ein KI-Assistent, der auf dieser Dokumentation basiert. Fragen Sie ihn nach Routing, Modulen, der CLI, der Smarty-Schicht oder der Bedeutung von pageAction(). Er zitiert seine Quellen.

Was steuert es

Standardmäßig läuft der Oracle vollständig auf Ihren eigenen Infrastrukturen.

Ebene	Backend	Standardmodell
Chat (Antwortgenerierung)	Ollama auf `https://your-ollama-host.example`	`qwen2.5-coder:14b`
Embeddings (RAG-Retrieval)	Ollama auf `https://your-ollama-host.example`	`nomic-embed-text`

Keine bezahlten API-Schlüssel. Ihre Daten verlassen Ihr Netzwerk nicht. Der 5-GPU-Cluster von Ollama, den Sie bereits betreiben, übernimmt die Last.

Wenn Sie lieber einen bezahlten Anbieter verwenden möchten – Claude für Chats und OpenAI für Embeddings – setzen Sie LLM_PROVIDER=anthropic und/oder EMBED_PROVIDER=openai sowie die entsprechenden API-Schlüssel. Die Codepfade sind identisch.

Wie es funktioniert

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]

Beim Build-Zeitpunkt durchläuft die Dokumentationssite jede Markdown-Seite, teilt sie an den Grenzen von H2/H3 in etwa 600-Token-Blöcken auf, bettet jedes Blatt mit nomic-embed-text ein und schreibt das Ergebnis in public/oracle-index.json. Keine Datenbank erforderlich.
Beim Anfrage-Zeitpunkt wird die Frage des Benutzers auf dieselbe Weise eingebettet, die nächsten Blöcke werden durch Kosinusähnlichkeit abgerufen und zu einem System-Prompt für das Chat-Modell zusammengefügt.
Antwortet das Chat-Modell im Sprach des Benutzers und bezieht sich auf die Quellenblöcke per URL.

Dateien

Datei	Zweck
`scripts/lib/providers.mjs`	Gemeinsamer Chat- und Embedding-Adapter (Ollama / Anthropic / OpenAI).
`scripts/build-oracle-index.mjs`	Erstellt `public/oracle-index.json` zur Build-Zeit.
`public/oracle-index.json`	Der eingeführte/Build-Ausgabe-Embedding-Index.
`src/pages/api/oracle.ts`	Der SSR-Endpunkt, an den das Chat-Widget POSTs. Bietet auch einen GET für Diagnosen.
`src/components/CosmicHeader.astro`	Der schwebende Launcher + Chat-Benutzeroberfläche.

Einmalige Einrichtung auf Ihrer Ollama.ai

Ziehen Sie die beiden Modelle herunter, die der Oracle verwendet:

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 ist bereits installiert (lebt getestet). nomic-embed-text fehlt noch; ohne es läuft der Oracle im Chat-Modus (ohne RAG).

Konfiguration durchführen

Der Oracle liest seine Konfiguration aus Umgebungsvariablen. Sinnvolle Standardwerte sind integriert.

# 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

Diagnose-Endpunkt

GET /api/oracle gibt die aktuelle Konfiguration zurück (keine Geheimnisse):

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" }
}

Nützlich zur Überprüfung, ob ein neu bereitgestellter Container den Back-End-Dienst verwendet, den Sie erwartet haben.

Datenschutz

Fragen und Gesprächshistorie werden an Ihren Ollama-Server gesendet. Sie werden nicht vom Docs-Site oder von Anthropic/OpenAI im Standard-Ollama-Konfiguration gespeichert.
Der OpenAI-Schlüssel (falls verwendet) wird nur für Embeddings aufgerufen.
Das Oracle-Widget selbst setzt keine Analysen oder Cookies.

Warum ein von Nibiru trainiertes Modell?

Die Roadmap (siehe AI Roadmap) besteht darin, eine LoRA auf der Exportdatei des Trainingskorpus zu feinabzustimmen, sodass das Chatmodell selbst Nibiru-nativ ist. Sobald dies bereitgestellt ist, wird die OLLAMA_CHAT_MODEL des Orakels auf das feinabgestimmte Modell umgeschaltet und der Systemprompt vereinfacht. Gleiches Code, intelligentere Antworten.

Try it

Öffnen Sie den Oracle (die gelbe Planeten, unten rechts) und versuchen Sie eines dieser Optionen:

“Wie erstelle ich ein neues Modul?”
“Was macht pageAction?”
“Zeige mir, wie ich einen JSON-Endpunkt verwalte.”
“Wie schreibe ich eine Migration?” (Deutsch funktioniert.)
“Authentifizierungsfluss erläutern” (Japanisch funktioniert.)