Lokal Ausführen

Die Dokumentationssite – und der Oracle, der sich im Ecke befindet – ist einfach eine Astro-App. Sie können sie auf drei Arten ausführen, abhängig davon, was Ihnen zur Verfügung steht.

Option A — Astro Entwickler-Server, your Ollama instance Backend (schnellste)

Der Oracle ruft Ihre gemeinsame Ollama unter https://your-ollama-host.example auf. Keine lokale GPU erforderlich, keine API-Schlüssel zu verwalten.

cd /home/stephan/PhpstormProjects/Nibiru/docs

# .env (copy from .env.example, defaults already point at your Ollama instance)
cp .env.example .env

npm install      # one-time
npm run dev      # http://localhost:4321

Öffnen Sie http://localhost:4321/. Klicken Sie auf den orangefarbenen Oracle-Launcher unten rechts und stellen Sie eine Frage.

Ziehen Sie das Einbettungsmodell einmal auf Ihrem Ollama-Host (Build-Zeit + Laufzeit) herunter:

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

Ohne es funktioniert der Oracle trotzdem – er läuft nur im Chat-Modus (ohne RAG) und antwortet auf Basis des modellbasierten Wissens. Mit ihm sind die Antworten an dieser Dokumentation angeordnet.

Erstellen Sie den Embedding-Index

npm run build:oracle    # writes public/oracle-index.json

Der Entwicklungs-Server wird es bei der nächsten Anfrage aufnehmen. Oder überspringen Sie diesen Schritt vollständig – der Laufzeitendpunkt verarbeitet einen fehlenden oder leeren Index sanft.

Laufzeitkonfiguration überprüfen

Der Endpunkt /api/oracle des Orakels antwortet auch auf GET mit seiner aktuellen Konfiguration (keine Geheimnisse):

curl http://localhost:4321/api/oracle
# {"status":"ok","llm":{"provider":"ollama","ollamaUrl":"https://your-ollama-host.example",
#  "model":"qwen2.5-coder:14b"},"embed":{...},"index":{...}}

Option B — Docker Compose, lokal

Näher an der Produktion. Baut das gleiche Image, das Sie schippen würden.

cd /home/stephan/PhpstormProjects/Nibiru/docs
cp .env.example .env

docker compose -f docker-compose.yml -f docker-compose.local.yml up --build

Die docker-compose.local.yml Überschreibung:

• Veröffentlicht 4321:4321, sodass die Anwendung unter http://localhost:4321/ erreichbar ist.
• Entfernt die Umgebungsvariablen VIRTUAL_HOST / LETSENCRYPT_HOST.
• Braucht kein nginx-proxy Netzwerk auf Ihrem Entwicklungssystem.

Der erste Build dauert 1-2 Minuten. Nachfolgende Neuaufbauten sind schnell (Docker speichert die Dep-Layer im Cache).

Option C — Völlig offline, lokale Ollama

Für airgapped Devs, Demos im Flugzeug oder das Brennen eigener GPUs.

# 1) Run Ollama on your laptop
ollama serve &

# 2) Pull a chat model (any of these works)
ollama pull qwen2.5-coder:14b      # 8 GB, recommended
# ollama pull qwen2.5-coder:1.5b   # 1 GB, faster but less accurate
# ollama pull llama3.2:3b          # 2 GB, alternative

# 3) Pull an embedding model
ollama pull nomic-embed-text

# 4) Point the docs at it
cd /home/stephan/PhpstormProjects/Nibiru/docs
cat > .env <<EOF
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_CHAT_MODEL=qwen2.5-coder:14b
OLLAMA_EMBED_MODEL=nomic-embed-text
EOF

npm run build:oracle
npm run dev

Jetzt ruft http://localhost:4321/api/oracle Ihren Laptop’s Ollama auf. Keine Internetverbindung erforderlich.

Wechsel zu Anthropic / OpenAI (falls Sie möchten)

Der Oracle unterstützt bezahlte APIs als Ersatzlösung. In .env:

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...

EMBED_PROVIDER=openai
OPENAI_API_KEY=sk-...

Nützlich, wenn Ihr Ollama ausfällt oder um die Antwortqualität zwischen Anbietern zu vergleichen.

Rauchtest-Schnellkennblatt

curl http://localhost:4321/                                    # 301 → /en/
curl -I http://localhost:4321/en/                              # 200
curl http://localhost:4321/api/oracle                          # GET = config
curl -X POST -H 'Content-Type: application/json' \
     -d '{"messages":[{"role":"user","content":"How do I create a module?"}]}' \
     http://localhost:4321/api/oracle | jq .answer

Wenn der letzte Aufruf eine echte Antwort zurückgibt, die ./nibiru -m erwähnt, ist Ihr Stack korrekt verbunden.

Problembehandlung

Oracle gibt “der Oracle konnte nicht antworten”. Der Ollama-Server ist nicht erreichbar oder das Chat-Modell wurde nicht abgerufen. Überprüfen Sie:```bash curl https://your-ollama-host.example/api/tags | jq ‘.models[].name’

**Oracle antwortet ohne Zitate.**
Der Einbettungsindex ist leer. Führen Sie nach dem Pullen von `nomic-embed-text` den Befehl `npm run build:oracle` erneut aus.

**Ollama gibt 404 model-not-found zurück.**
Laden Sie das Modell herunter, z.B.:```bash
curl https://your-ollama-host.example/api/pull -d '{"name":"qwen2.5-coder:14b"}'

ECONNREFUSED 127.0.0.1:11434 in Option C. Der lokale Ollama läuft nicht. Starten Sie ihn mit ollama serve & (oder über Ihren Systemdienst).