ローカルで実行する

ドキュメントサイトとコーナーに住むOracleは、単なるAstroアプリです。手元にあるもの次第で3つの方法で実行できます。

オプション A — Astro 開発サーバー、your Ollama instance バックエンド（最速）

Oracle は、https://your-ollama-host.example の共有 Ollama を呼び出します。ローカルの GPU は必要ありませんし、API キーを管理する必要もありません。

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

http://localhost:4321/を開いてください。右下のオレンジ色のOracleランチャーをクリックし、何でも尋ねてください。

Ollamaホスト上で1回だけ埋め込みモデルを取得（ビルド時+実行時）:

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

これなしで、Oracleはまだ動作します——それは単にチャットのみ（no-RAG）モードで実行され、モデルのパラメトリックな知識から回答されます。これがあれば、回答はこのドキュメンテーションに基づいています。

エンベディングインデックスの構築

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

開発サーバーは次のリクエストでそれを検出します。またはこのステップを完全にスキップすることもできます——ランタイムエンドポイントは欠落しているか空のインデックスを適切に対応します。

ランタイム構成を検査する

Oracleの/api/oracleエンドポイントも、現在の設定（シークレットなし）でGETリクエストに応答します。

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

オプションB — ローカルでのDocker Compose

本番に近づいています。出荷するのと同じイメージをビルドします。

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

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

docker-compose.local.yml のオーバーライド:

• 4321:4321 を公開して、アプリケーションが http://localhost:4321/ で到達可能になります。
• VIRTUAL_HOST / LETSENCRYPT_HOST 環境変数を削除します。
• 開発用マシンでは nginx-proxy ネットワークが必要ありません。

初回のビルドは1-2分かかります。その後の再ビルドは速いです（Dockerは依存関係層をキャッシュします）。

オプション C — 完全にオフライン、ローカルの Ollama

オフライン開発、飛行機でデモを行う場合、または独自の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

現在、http://localhost:4321/api/oracle はあなたのノートパソコンの Ollama を呼び出します。インターネットは必要ありません。

Anthropic / OpenAI への切り替え（ご希望の場合）

The Oracle supports paid APIs as a fallback. In .env:

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

EMBED_PROVIDER=openai
OPENAI_API_KEY=sk-...

Ollamaがダウンしている場合や、異なるプロバイダー間で回答の品質を比較するのに役立ちます。

スモークテストのチートシート

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

最後の呼び出しが ./nibiru -m を言及する実際の回答を返した場合、スタックが正しく接続されています。

トラブルシューティング

Oracle は「Oracle が回答することができませんでした」を返します。 Ollama サーバーにアクセスできないか、チャットモデルがプルされていない可能性があります。確認してください：```bash curl https://your-ollama-host.example/api/tags | jq ‘.models[].name’

**Oracle は引用せずに回答します。**
埋め込みインデックスが空です。`nomic-embed-text` をプルした後、`npm run build:oracle` を再実行してください。

**Ollamaが404 model-not-foundを返します。**
モデルを取得してください、例：```bash
curl https://your-ollama-host.example/api/pull -d '{"name":"qwen2.5-coder:14b"}'

ECONNREFUSED 127.0.0.1:11434 オプションCで。 ローカルのOllamaが実行されていません。ollama serve &（またはシステムサービス経由で）で開始してください。