router

# Weave Router **하나의 엔드포인트. 모든 모델. 항상 올바른 모델.** Weave Router는 Anthropic, OpenAI, Gemini용 드롭인 프록시로, 모든 요청에 대해 자동으로 최적의 모델을 선택합니다. 분위기 기반 프롬프트 대신 [Avengers-Pro](https://arxiv.org/abs/2508.12631) 연구 논문에서 파생된 클러스터 스코어러와 함께 소형 온박스 임베더를 사용하여 활성화된 공급자의 각 요청을 올바른 모델로 라우팅합니다. ## 주요 기능 - **작업별 라우팅** — 클러스터 스코어러가 모든 업스트림 API 요청에 대해 올바른 모델을 선택하여 턴 단위가 아닌 작업 단위로 라우팅합니다. - **모든 API 지원** — 스트리밍, 도구, 비전을 포함한 Anthropic Messages, OpenAI Chat Completions, Gemini 네이티브 API를 지원합니다. - **OSS 모델 지원** — OpenRouter 또는 모든 OpenAI 호환 엔드포인트를 통해 DeepSeek, Kimi, GLM, Qwen, Llama, Mistral을 지원합니다. - **기본 BYOK** — 공급자 키는 사용자 박스에 남아 있으며, 저장 시 암호화됩니다. - **관찰 가능성** — OTLP 추적을 기본 제공하며, Weave 대시보드 또는 Honeycomb, Datadog, Grafana 같은 모든 OTLP 호환 수집기에서 확인할 수 있습니다. ## 빠른 시작 가장 빠른 시작 방법은 호스팅된 Weave Router를 사용하는 것입니다: ```bash npx @weave-os/router ``` 설치 프로그램은 어떤 도구(Claude Code, Codex, opencode, pi)를 사용할지 묻고, 범위(사용자 vs 프로젝트)를 안내하며, 라우터 키를 가져오고 올바른 구성 파일을 연결합니다. 다른 옵션은 다음과 같습니다: ```bash npx @weave-os/router --claude # 선택기 건너뛰기, Claude Code npx @weave-os/router --codex # 선택기 건너뛰기, OpenAI Codex CLI npx @weave-os/router --opencode # 선택기 건너뛰기, opencode npx @weave-os/router --pi # 선택기 건너뛰기, pi + Loom UI npx @weave-os/router --scope project # 저장소별, settings.json 커밋 npx @weave-os/router --local # 자체 호스팅 localhost:8080 npx @weave-os/router --base-url https://router.acme.internal npx @weave-os/router@0.1.0 # 버전 고정 ``` Node ≥ 18이 필요합니다. 전체 플래그 참조는 [install/npm/README.md](install/npm/README.md)에 있습니다. ## 자체 호스팅 자체 박스에서 라우터와 대시보드를 실행하려면: ```bash # 1. 공급자 키를 넣습니다. OpenRouter가 권장 기본값입니다. echo "OPENROUTER_API_KEY=sk-or-v1-..." >> .env.local # 2. 대시보드 비밀번호를 설정합니다. echo "ROUTER_ADMIN_PASSWORD=replace-with-a-strong-password" >> .env.local # 3. Postgres + 라우터를 :8080에서 부팅하고 rk_ 키를 시드합니다. make full-setup ``` 라우터는 http://localhost:8080, 대시보드는 http://localhost:8080/ui/에서 실행되며, `rk_...` 키는 로그에 출력됩니다. ### API 호출 예시 ```bash # Anthropic처럼 호출 curl -sS http://localhost:8080/v1/messages \ -H "Authorization: Bearer rk_..." \ -d '{"model":"claude-sonnet-4-5","max_tokens":256, "messages":[{"role":"user","content":"hi"}]}' # ...또는 OpenAI처럼 호출 curl -sS http://localhost:8080/v1/chat/completions \ -H "Authorization: Bearer rk_..." \ -d '{"model":"gpt-4o-mini", "messages":[{"role":"user","content":"hi"}]}' # 프록시 없이 라우팅 결정만 확인 curl -sS http://localhost:8080/v1/route -H "Authorization: Bearer rk_..." -d '...' ``` ## 아키텍처 회색 상자만 사용자 머신 밖에 있습니다. 라우터, 스코어러, Postgres, 공급자 키는 모두 로컬에 유지되며, 프롬프트는 라우터에서 구성된 공급자로 직접 이동하며 Weave로 전송되지 않습니다. ```mermaid flowchart LR client["Claude Code, Codex, opencode,<br/>pi, Cursor, your own app"] router["Router :8080<br/>/v1/messages · /v1/chat/completions<br/>/v1beta/models · /v1/route"] scorer["Cluster scorer<br/>in-process ONNX embedder"] hmm["HMM policy sidecar :8093<br/>optional, make up-hmm"] pg[("Postgres<br/>installations, rk_ keys,<br/>encrypted BYOK keys, usage")] ui["Dashboard /ui<br/>selfhosted mode only"] providers["Anthropic · OpenAI · Gemini<br/>OpenRouter and any<br/>OpenAI-compatible endpoint"] otel["Your OTLP collector<br/>Honeycomb, Datadog, Grafana"] client -->|"rk_… bearer token,<br/>streamed response back"| router router -->|"embed and score the action"| scorer router -.->|"ROUTER_DEFAULT_STRATEGY=hmm"| hmm router -->|"auth, config, usage"| pg pg --> ui router -->|"provider key from env or BYOK"| providers router -.->|"spans and usage logs"| otel ``` 멀티 레플리카 배포에는 캐시 무효화를 위한 Pub/Sub(`PUBSUB_*`)도 필요합니다. `docker compose`가 에뮬레이터를 실행합니다. ## 선택 사항: HMM 정책 사이드카 기본 스택은 인프로세스 클러스터 스코어러를 사용합니다. 고정 HMM 정책을 컴패니언 컨테이너로 실행하려면 Google API 키를 추가하고 옵트인 대상을 사용하세요: ```bash echo 'GOOGLE_API_KEY=...' >> .env.local make up-hmm ``` 이것은 기본 전략을 변경하지 않습니다. 아티팩트 검증, 임베딩 호환성, 명시적 HMM 선택은 [sidecars/hmm/README.md](sidecars/hmm/README.md)를 참조하세요. ## 도구 통합 **Claude Code.** `make install-cc`를 실행하여 로컬 자체 호스팅 라우터에 Claude Code를 연결합니다(`make full-setup` 종료 시 자동 호출됨). 호스팅 라우터의 경우 위의 `npx @weave-os/router`를 사용하세요. **Codex** (OpenAI CLI). `npx @weave-os/router --codex`는 관리되는 `[model_providers.weave]` 블록으로 `~/.codex/config.toml`(또는 `--scope project`로 `<repo>/.codex/config.toml`)을 패치하고 `model_provider = "weave"`를 설정합니다. 공급자는 Codex의 기존 ChatGPT OAuth 로그인을 유지하면서 라우터 키는 `X-Weave-Router-Key` HTTP 헤더에 실립니다. ## 라이선스 Elastic License v2 (ELv2)에 따라 라이선스가 부여됩니다. --- *[Weave](https://www.workweave.ai) 제작: Robinhood, PostHog, Reducto 및 수백 개 기업이 사용하는 1위 엔지니어링 인텔리전스 플랫폼.*