Exécutez-le localement

Le site de documentation — ainsi que l’Oracle qui se trouve dans le coin — est simplement une application Astro. Vous pouvez la lancer de trois façons en fonction de ce que vous avez à portée de main.

Option A — Serveur de développement Astro, backend your Ollama instance (le plus rapide)

L’Oracle appelle votre Ollama partagé à https://your-ollama-host.example. Aucun GPU local nécessaire, aucune clé API à gérer.

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

Ouvrez http://localhost:4321/. Cliquez sur le lanceur orange d’Oracle en bas à droite et posez une question.

Tirez le modèle d’incrustation une seule fois sur votre hôte Ollama (au moment de la construction + au moment de l’exécution) :

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

Sans cela, l’Oracle fonctionne toujours — elle ne fait que s’exécuter en mode conversationnel uniquement (sans RAG) et répond à partir des connaissances paramétriques du modèle. Avec cela, les réponses sont ancrées dans cette documentation.

Construire l’index d’embedding

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

Le serveur de développement le détectera lors du prochain appel. Ou bien, ignorez complètement cette étape : le point d’entrée au moment de l’exécution gère une absence/index vide avec élégance.

Vérifier la configuration d’exécution

Le point d’accès /api/oracle de l’Oracle répond également à la méthode GET avec sa configuration actuelle (sans les secrets) :

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, localement

Plus proche de la production. Construit l’image que vous délivreriez.

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

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

Le remplacement docker-compose.local.yml:

• Publie 4321:4321 afin que l’application soit accessible à http://localhost:4321/.
• Supprime les variables d’environnement VIRTUAL_HOST / LETSENCRYPT_HOST.
• N’a pas besoin d’un réseau nginx-proxy sur votre boîte de développement.

La première construction prend 1 à 2 minutes. Les reconstructions ultérieures sont rapides (Docker met en cache la couche des dépendances).

Option C — Pleinement hors ligne, Ollama local

Pour le développement hors ligne, les démos en avion ou la création de votre propre GPU.

# 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

Maintenant, http://localhost:4321/api/oracle appelle votre ordinateur portable Ollama. Aucune connexion Internet n’est requise.

Passage à Anthropic / OpenAI (si vous le souhaitez)

L’Oracle prend en charge les API payantes comme alternative. Dans le fichier .env :

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

EMBED_PROVIDER=openai
OPENAI_API_KEY=sk-...

Utile si votre Ollama est hors service ou pour comparer la qualité des réponses entre les fournisseurs.

Feuille de référence pour les tests fumeurs

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

Si l’appel final retourne une réponse réelle qui mentionne ./nibiru -m, votre pile est correctement câblée.

Dépannage

Oracle retourne “le Oracle ne peut pas répondre”. Le serveur Ollama est inaccessible ou le modèle de conversation n’est pas extrait. Vérifiez :```bash curl https://your-ollama-host.example/api/tags | jq ‘.models[].name’

**Oracle répond sans références.**
L'index d'embedding est vide. Réexécutez `npm run build:oracle` après avoir tiré `nomic-embed-text`.

**Ollama retourne 404 modèle non trouvé.**
Tirez le modèle, par exemple :```bash
curl https://your-ollama-host.example/api/pull -d '{"name":"qwen2.5-coder:14b"}'

ECONNREFUSED 127.0.0.1:11434 dans l’option C. Le local Ollama n’est pas en cours d’exécution. Démarrez-le avec ollama serve & (ou via votre service système).