完全ローカルLLMテスト環境

外部APIを一切使わず、ローカルLLM + ローカルMCP（DuckDB）でAgentic AI Serverを動かす手順。

前提条件

コンポーネント	用途
LM Studio	ローカルLLMサーバー (OpenAI互換API)
uv	Pythonパッケージ管理
hy/vs	セマンティック検索MCPサーバー + DuckDB

セットアップ

1. LM Studio でモデルをロード

LM Studio を起動
qwen/qwen3.5-9b をダウンロード・ロード
Server を起動（デフォルト: http://127.0.0.1:1234）

他のモデルを使う場合は server/llm_config.local.yaml の model を変更。

2. 依存関係のインストール

cd server
uv sync

3. 起動

./start-local.sh

これだけで以下が順に起動する:

vs Web Server (port 8787) — DuckDB (hy/vs/data/ppe.duckdb) をバックエンド
vs MCP Server (port 8788) — Web Server経由でセマンティック検索ツールを提供
Agentic AI Server (port 8000) — ローカルLLM + vs MCPで動作

4. アクセス

通常UI: http://localhost:8000/
ストリーミングUI: http://localhost:8000/stream
プランナーUI: http://localhost:8000/planner

設定ファイル

`server/llm_config.local.yaml` — LLM設定

default:
  provider: openai-compatible
  model: qwen/qwen3.5-9b
  base_url: http://127.0.0.1:1234/v1
  api_key: lm-studio

roles:
  agent:
    timeout: 120.0      # ローカルLLMは遅いのでタイムアウト延長
  summary:
    timeout: 60.0
  planner:
    timeout: 120.0
  evaluator:
    timeout: 60.0

`.mcp_servers.local` — MCP設定

{
    "httpStreamableServers": {
        "vs": {
            "url": "http://127.0.0.1:8788/mcp"
        }
    }
}

vs MCPが提供するツール（4つ）: - search_docs — ハイブリッド検索（ベクトル + BM25） - get_chunk_detail — チャンクの全文取得 - list_facets — タグ・コンセプト一覧 - get_db_stats — DB統計情報

起動オプション

# MCPなしで起動（LLMのみテスト）
./start-local.sh --no-mcp

# ポート変更
./start-local.sh --port 9000

# 開発モード（自動リロード）
./start-local.sh --reload

環境変数

start-local.sh が自動で設定する:

変数	値	説明
`FORCE_NON_STREAMING`	`1`	ストリーミング無効化（ローカルLLM向け）

アーキテクチャ

LM Studio (port 1234)          DuckDB (ppe.duckdb)
  qwen/qwen3.5-9b                    |
       |                        vs Web Server (port 8787)
       |                             |
       |                        vs MCP Server (port 8788)
       |                             |
       +-------- Agentic AI Server (port 8000) --------+
                      |
                 http://localhost:8000/

既知の制限事項

ストリーミング非対応: FORCE_NON_STREAMING=1 で非ストリーミングモードで動作。ストリーミングUIは使用不可。
レスポンス速度: ローカルLLMはクラウドAPIより遅い。タイムアウトは120秒に設定済み。
ツール呼び出し精度: モデルによってはfunction calling精度が低く、ツールを呼ばずに回答する場合がある。
URL生成: 検索結果にURLフィールドは含まれないため、LLMが回答中にURLを生成した場合はハルシネーション（偽URL）の可能性が高い。

トラブルシューティング

LM Studio に接続できない

curl http://127.0.0.1:1234/v1/models

でモデル一覧が返るか確認。返らなければLM Studioのサーバーを起動する。

vs MCP に接続できない

curl http://127.0.0.1:8787/healthz

でvs Web Serverの状態を確認。ログは .vs_web.log, .vs_mcp.log を参照。

タイムアウトする

server/llm_config.local.yaml の timeout を増やす。または軽量モデルに切り替える。