คู่มือ BCAiRouter

groq/llama-3.3-70b-versatile
openrouter/qwen/qwen3-coder:free
cerebras/qwen-3-235b-a22b-instruct-2507
mistral/mistral-large-2411

# Typhoon (SCB 10X) — sign up: https://opentyphoon.ai
typhoon/typhoon-v2.5-30b-a3b-instruct

# ThaiLLM (NSTDA national platform) — sign up: https://playground.thaillm.or.th
# 4 โมเดลของคนไทยใต้ endpoint เดียว:
thaillm/OpenThaiGPT-ThaiLLM-8B-Instruct-v7.2     # AIEAT
thaillm/Typhoon-S-ThaiLLM-8B-Instruct            # SCB 10X
thaillm/Pathumma-ThaiLLM-qwen3-8b-think-3.0.0    # NECTEC — มี thinking!
thaillm/THaLLE-0.2-ThaiLLM-8B-fa                 # KBTG

{
  "reasoning": { "effort": "medium" },     // OpenRouter / Anthropic / OpenAI o-series
  "enable_thinking": true,                  // Qwen3 / DashScope / vLLM
  "max_tokens": 2000                        // เผื่อพื้นที่ trace
}

{
  "model": "thaillm/Pathumma-ThaiLLM-qwen3-8b-think-3.0.0",
  "messages": [...],
  "reasoning": false      // หรือ "enable_thinking": false
}

docker compose down
docker volume rm bcai-router_bcai-router-data
docker compose up -d --build

/admin/* + mutating /api/*  →  1. Bearer GATEWAY_API_KEY     →  pass
                           →  2. Signed bcai_admin cookie  →  pass  (password)
                           →  3. Google session + owner   →  pass  (OAuth)
                           →  else  →  /login (page) หรือ 401 (API)

/v1/*   →  Bearer sk-gw-* (master) หรือ Bearer bcai_live_* เท่านั้น

# จัดการ gateway keys
GET    /api/admin/keys                 → รายการ (hash เท่านั้น ไม่มี plaintext)
POST   /api/admin/keys                 → สร้าง { label, expiresAt?, notes? } — ส่ง token ครั้งเดียว
PATCH  /api/admin/keys/:id             → { enabled: true|false }
DELETE /api/admin/keys/:id             → revoke ถาวร

# Circuit breaker (per-model)
GET    /api/admin/circuits             → { open[], halfOpen[], warnings[], summary }
DELETE /api/admin/circuits?provider=X&modelId=Y   → reset 1 คู่
DELETE /api/admin/circuits             → reset ทั้งหมด (nuclear)

# Performance insights (public — for dashboard widget)
GET    /api/perf-insights              → {
  requestsLastHour, p50/p95 latency, errorRate,
  counts: { cache:hit/miss, hedge:win/loss, spec:fire/win, sticky:hit, demote:rate-limit },
  rates:  { cacheHitRate, hedgeWinRate, speculativeWinRate, stickyPinRate }
}

docker run --rm \
  -e DASHSCOPE_BASE_URL=http://localhost:3334/v1 \
  -e DASHSCOPE_API_KEY=dummy \
  -e THCLAWS_DISABLE_KEYCHAIN=1 \
  -v "$PWD:/workspace" -w /workspace \
  thclaws-bcairouter:local \
  -p -m bcai/auto --permission-mode auto \
  "สรุปโปรเจกต์นี้"

{
  "models": {
    "providers": {
      "custom-host-docker-internal-3334": {
        "baseUrl": "http://host.docker.internal:3334/v1",
        "apiKey": "dummy",
        "api": "openai-completions",
        "models": [{ "id": "bcai/auto", "contextWindow": 131072 }]
      }
    }
  }
}

{
  "apiProvider": "openai-completions",
  "openAiBaseUrl": "http://host.docker.internal:3334/v1",
  "openAiModelId": "bcai/auto",
  "openAiApiKey": "dummy",
  "contextWindow": 131072,
  "gateway": {
    "bind": "lan",
    "allowedOrigins": [
      "http://host.docker.internal:3334",
      "http://localhost:3334"
    ]
  }
}

[model.fallback]
provider = "nous-portal"
api_key_env = "NOUS_API_KEY"
model = "Hermes-3-Llama-3.1-405B"

curl http://localhost:3334/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bcai/auto",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "อธิบายรูปนี้"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
      ]
    }]
  }'

curl http://localhost:3334/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bcai/tools",
    "messages": [{"role": "user", "content": "กรุงเทพอากาศเป็นยังไง"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "ดูสภาพอากาศเมือง",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }]
  }'

# หา model ภาษาไทยที่รับ context 200K+ ท็อป 3
curl "http://localhost:3334/v1/models/search?category=thai&min_context=200000&top=3"

# หา model tools calling
curl "http://localhost:3334/v1/models/search?category=code&supports_tools=1&top=5"

curl -X POST http://localhost:3334/v1/compare \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role":"user","content":"อธิบาย recursion"}],
    "models": [
      "groq/moonshotai/kimi-k2-instruct-0905",
      "cerebras/qwen-3-235b-a22b-instruct-2507",
      "nvidia/meta/llama-4-maverick-17b-128e-instruct"
    ],
    "max_tokens": 200,
    "timeout_ms": 30000
  }'

curl -X POST http://localhost:3334/v1/structured \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bcai/auto",
    "messages": [{"role":"user","content":"Describe a fruit"}],
    "schema": {
      "type": "object",
      "required": ["name", "color", "taste"],
      "properties": {
        "name": {"type": "string"},
        "color": {"type": "string"},
        "sweetness": {"type": "integer"}
      }
    },
    "max_retries": 2
  }'

# Response: { ok, attempts, data: { name, color, taste, sweetness }, model, provider, latency_ms, request_ids }

# สร้าง
curl -X POST http://localhost:3334/v1/prompts \
  -H "Content-Type: application/json" \
  -d '{"name":"pirate","content":"You are a pirate. Short answers only.","description":"Pirate persona"}'

# ใช้ในแชท — แค่ใส่ "prompt": "pirate"
curl -X POST http://localhost:3334/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"bcai/auto","prompt":"pirate","messages":[{"role":"user","content":"how to fish"}]}'

# รายการทั้งหมด
curl http://localhost:3334/v1/prompts

# แก้ไข / ลบ
curl -X PUT    http://localhost:3334/v1/prompts/pirate -d '{...}'
curl -X DELETE http://localhost:3334/v1/prompts/pirate

# ยิง chat ธรรมดา
curl -D - http://localhost:3334/v1/chat/completions \
  -d '{"model":"bcai/auto","messages":[{"role":"user","content":"hi"}]}'
# → response headers มี: X-BCAiRouter-Request-Id: 5m3obi

# ดู trace
curl http://localhost:3334/v1/trace/5m3obi
# → { requestId, found, entry: { resolved_model, provider, latency_ms, input_tokens, ... } }

curl "http://localhost:3334/api/my-stats?window=24h"
# → { total, success, p50_latency_ms, p95_latency_ms, p99_latency_ms,
#     top_models: [...], by_hour: [...] }
# window: 1h | 6h | 24h | 7d | 30d

curl -X POST http://localhost:3334/v1/chat/completions \
  -H "X-BCAiRouter-Prefer: groq,cerebras" \
  -H "X-BCAiRouter-Exclude: mistral" \
  -H "X-BCAiRouter-Strategy: fastest" \
  -H "X-BCAiRouter-Max-Latency: 3000" \
  -d '{"model":"bcai/auto","messages":[...]}'

# virtual models (bcai/auto, bcai/fast, bcai/tools, bcai/thai, bcai/consensus)
curl http://localhost:3334/v1/models/bcai/tools
# → { "id": "bcai/tools", "object": "model", ... }

# provider/model format
curl http://localhost:3334/v1/models/groq/llama-3.3-70b-versatile
# → { "id": "groq/llama-3.3-70b-versatile", ... }

# ถ้าได้ HTML หรือ 404 — ให้ rebuild container
docker compose up -d --build bcai-router

docker exec bcai-router-postgres-1 psql -U bcai -d bcairouter \
  -c "SELECT COUNT(*) FROM health_logs WHERE cooldown_until > now();"