Kosha Model Discovery

kosha-discovery

告诉你的 Agent 或代码该使用哪个模型，以及费用是多少。

kosha 可发现 46 个提供商和本地运行时中的模型，在密钥已有的任何位置（环境变量、Claude CLI、Codex、gcloud ADC、AWS SSO）查找 API 密钥，补全价格和上下文限制，并回答诸如我实际持有密钥、支持工具调用且上下文为 128k 的最便宜模型是什么这样的问题。它提供 TypeScript 库、CLI、HTTP API、带支出账本的 OpenAI 兼容代理，以及 MCP 服务。

即使没有任何 API 密钥，它也能正常工作——发现功能会回退到公开的 models.dev 和 LiteLLM 目录，因此在新机器上也能使用 kosha list。

安装

npm install @sriinnu/kosha-discovery       # library / server
npm install -g @sriinnu/kosha-discovery    # global `kosha` CLI

需要 Node.js 22+。

快速开始

库

import { createKosha } from "@sriinnu/kosha-discovery";

const kosha = await createKosha();

const models   = kosha.models();                          // ModelCard[] across every provider
const cheapest = kosha.cheapestModels({ role: "image" }); // ranked by price, with missingCredentials
const sonnet   = kosha.model("sonnet");                   // alias → canonical ID; undefined if unknown
console.log(sonnet?.pricing); // { inputPerMillion: 2, outputPerMillion: 10, cacheReadPerMillion: 0.2, ... }

CLI

kosha discover                       # query every provider; writes ~/.kosha/cache and the manifest
kosha list --provider anthropic      # read from the local cache
kosha model sonnet                   # one model, alias-aware
kosha routes claude-opus-5-5         # every serving route for a model (direct, OpenRouter, Bedrock, …)
kosha cheapest --role embeddings     # rank by price for a role
kosha doctor --ci --model opus,gpt6  # fail CI if a model you pin is deprecated, retiring, or gone
kosha spend --since 2026-09-01       # roll up the proxy's spend ledger
kosha refresh                        # bypass the cache and re-discover
kosha serve --port 3000              # HTTP API + proxy; binds 127.0.0.1 (see Proxy below)

每条命令都支持 --json。其余命令请参阅 kosha --help。

每次发现后，稳定版 v1 清单都会写入 ~/.kosha/registry.json：

jq '.models[] | select(.pricing.inputPerMillion < 0.1) | .modelId' ~/.kosha/registry.json

GitHub Action

当代码固定使用的模型已弃用、即将停用，或已不再由任何提供商提供时，让构建失败：

- uses: sriinnu/kosha-discovery@v1
  with:
    models: |
      claude-opus-5-5
      gpt-6-sol
      sonnet

与使用任何 Action 一样，请将其固定到提交 SHA，而不是会变动的标签。该 Action 运行的是其发布时附带的 kosha 版本，而不是 latest，因此在你更新固定版本之前，新版 npm 发布不会改变 CI 运行的内容。

它会针对公开目录运行 kosha doctor --ci --model …（不需要提供商密钥），在作业摘要中写入表格，并为每个失败的模型添加注释。若转售商停用了其中一条路由，但模型所属的提供商仍在提供该模型，则只会报告，不会导致构建失败；deprecation-window（默认为 30 天）用于设置提前多久的停用日期会被计入。

公开快照

每周运行一次发现任务，并通过稳定 URL 发布完整快照，涵盖 kosha 无需你的密钥就能看到的每个提供商、模型、价格和限制：

curl -sL https://github.com/sriinnu/kosha-discovery/releases/download/snapshot-latest/kosha-latest.json \
  | jq '.modelCount, .providerCount'

快照作为发布资源提供，而不是仓库中的文件：快照约为 2.8 MB，且会随着添加提供商而增大；若每周都提交到仓库，一年就会给本应供人克隆的仓库带来约 150 MB 已过时的数据。带日期的 snapshot-YYYY-MM-DD 预发布版本会保留一段较短的历史记录以供比较，最多保留最近两个版本；只有在出现更新的版本后，才会删除较旧的版本。

每个快照的发布说明都会列出与上一个版本相比的变化——新增模型、价格调整、新增弃用项和移除项。你也可以在本地运行相同的差异比较：pnpm snapshot:diff old.json new.json。

HTTP API

GET  /api/models?provider=&originProvider=&mode=&capability=
GET  /api/models/:idOrAlias             GET  /api/models/:idOrAlias/routes
GET  /api/models/cheapest?role=…        GET  /api/capabilities
GET  /api/providers[/:id]               GET  /api/roles
GET  /api/resolve/:alias                GET  /api/discovery-errors
GET  /api/discovery[/delta|/watch|/cheapest|/binding]   (stable v1 contract)
POST /api/refresh                       GET  /health          GET  /metrics
GET  /proxy/v1/models                   POST /proxy/v1/chat/completions

参数和响应结构：docs/api.md。

代理

kosha serve 还会在 /proxy/v1 暴露一个兼容 OpenAI 的端点。将任意 OpenAI SDK 指向该端点；代理会解析模型或别名，选择你持有凭据的提供商，注入上游密钥，转发请求，并在支出账本中写入一条记录。

kosha serve   # start on :3000

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:3000/proxy/v1",
  apiKey:  "not-used",   // kosha resolves credentials from env
});

// Use any canonical model ID or alias
const res = await client.chat.completions.create({
  model: "sonnet",
  messages: [{ role: "user", content: "hello" }],
});

// Let kosha pick the cheapest model you have a key for
const cheap = await client.chat.completions.create({
  model: "kosha:cheapest",
  messages: [{ role: "user", content: "hello" }],
});

// Cheapest model with tool_use and at least 128k context
const routed = await client.chat.completions.create({
  model: "kosha:cheapest[tool_use,128k]",
  messages: [{ role: "user", content: "hello" }],
});

kosha:cheapest 筛选语法（以逗号分隔，可组合使用）：

筛选条件	示例	含义
能力	tool_use、vision	模型必须带有此标签
<N>k	128k、200k	最小上下文窗口
provider:<id>	provider:groq	固定使用特定提供商

kosha:fastest、kosha:reliable 和 kosha:balanced 使用相同的筛选条件，并根据观测到的延迟和断路器状态排序，而非按价格排序。

每个响应都包含 x-kosha-model、x-kosha-provider、x-kosha-requested、x-kosha-attempt-chain 和 x-kosha-estimated-cost-usd；非流式响应会在上游返回用量块时添加 x-kosha-actual-cost-usd。

代理可以转发的内容：

上游线路格式	提供商	支持情况
兼容 OpenAI	OpenAI、Ollama、OpenRouter、Vercel、Groq、Together、Fireworks、DeepInfra、…	直通转发，包括流式传输
Anthropic Messages	Anthropic	转换支持：流式传输、工具、image_url、response_format、reasoning_effort；音频输入和非函数工具会为同一模型回退到兼容 OpenAI 的路由
云 SDK	Google、Bedrock、Vertex	仅发现，暂不支持代理
非聊天／其他线路	TypeSafe、Thinking Machines	仅发现——TypeSafe 的 System One 端点不是聊天 API，而 Tinker's Anthropic 线路与 Anthropic 自身的线路不同

对外开放服务前需要了解的重要默认设置：服务器绑定到 127.0.0.1。传入 --host 0.0.0.0（或设置 KOSHA_HOST）以监听网络接口，并设置 KOSHA_PROXY_TOKEN，使 /proxy/* 和 POST /api/refresh 必须通过 Authorization: Bearer <token> 或 x-kosha-token 进行身份验证。KOSHA_MONTHLY_BUDGET_USD 用于限制每个日历月的支出。参考：docs/api.md、docs/operations.md。

MCP 服务

kosha-mcp 通过标准输入／输出使用 Model Context Protocol 提供注册表服务，因此 Agent 无需 HTTP 服务器即可调用 kosha_query_models、kosha_cheapest_model、kosha_ranked_routes、kosha_model_detail、kosha_model_routes、kosha_resolve_alias、kosha_provider_health 和 kosha_context_strategy。

claude mcp add kosha -- kosha-mcp

它已发布到 MCP 注册表，名称为 io.github.sriinnu/kosha-discovery，因此能够读取该注册表的客户端可以直接安装，无需手动执行命令。清单文件为 server.json。

每个提供商的密钥均为可选项。即使完全没有凭据，服务仍会根据公开的 models.dev 和 LiteLLM 目录以及精心整理的离线列表提供响应，因此在全新机器上也很实用。

工具和协议详情：docs/mcp.md。

支持的提供商

46 个提供商。每个提供商都在 src/provider-catalog.ts 中有一个描述符；大多数兼容 OpenAI 的提供商由 src/discovery/generic-openai.ts 中的 GENERIC_OPENAI_PROVIDERS 驱动，而不是通过手写类实现。

提供商	发现方式	凭据来源
Anthropic	GET /v1/models（上下文、输出上限和能力从 API 读取）	ANTHROPIC_API_KEY、Claude CLI、Codex CLI
OpenAI	GET /v1/models	OPENAI_API_KEY、GitHub Copilot 令牌
Google	GET /v1beta/models	GOOGLE_API_KEY、GEMINI_API_KEY、Gemini CLI、gcloud
AWS Bedrock	SDK → CLI → 公共目录 → 静态列表	AWS_ACCESS_KEY_ID、~/.aws/credentials、SSO、IAM
Vertex AI	API → gcloud → 公共目录 → 静态列表	GOOGLE_APPLICATION_CREDENTIALS、ADC
Ollama、llama.cpp、LM Studio、vLLM	本地 HTTP API	无
OpenRouter	API	OPENROUTER_API_KEY（可选；未认证时会受到速率限制）
Vercel AI Gateway	GET /v1/models	AI_GATEWAY_API_KEY、VERCEL_OIDC_TOKEN（无需凭据即可发现；执行需要其中一个）
NVIDIA、Together、Fireworks、Groq、Cerebras、Cohere、DeepInfra、Perplexity	兼容 OpenAI 的 API	<PROVIDER>_API_KEY
DeepSeek、Mistral、Moonshot（Kimi）、GLM（Zhipu）、Z.AI、MiniMax	兼容 OpenAI 的 API	<PROVIDER>_API_KEY
xAI（Grok）	GET /v1/models；Grok Imagine 分为图像和视频	XAI_API_KEY
TypeSafe（System One / Jev）	GET /v1/models — 返回的是 judgment 模型，而非聊天模型	TYPESAFE_API_KEY、JEV_API_KEY
Thinking Machines（Inkling）	Anthropic-wire 端点，无模型列表 — 仅使用公共目录	TINKER_API_KEY
Alibaba Model Studio（Qwen）、Volcengine Ark（Doubao）、Inception（Mercury）、AI21（Jamba）、Upstage（Solar）、StepFun、Meta（Muse Spark）	兼容 OpenAI 的 API	DASHSCOPE_API_KEY、ARK_API_KEY、INCEPTION_API_KEY、AI21_API_KEY、UPSTAGE_API_KEY、STEPFUN_API_KEY、META_MODEL_API_KEY
Baseten、Nebius Token Factory、Novita AI、SiliconFlow、Hugging Face、Ollama Cloud	兼容 OpenAI 的 API	<PROVIDER>_API_KEY、HF_TOKEN

区域配对

一些提供商为国际流量和中国大陆流量分别使用不同的主机，并使用不同的密钥和价格表——Qwen 2.5 72B 的国际版输入价格为 $1.40/M，而中国版为 $0.574/M。合并后，模型价格将取决于最后响应的是哪个主机，因此每个区域都作为独立的提供商：

国际版	中国版	差异
moonshot（api.moonshot.ai）	moonshot-cn（api.moonshot.cn）	主机、密钥
minimax（api.minimax.io）	minimax-cn（api.minimaxi.com）	主机、密钥
alibaba（dashscope-intl）	alibaba-cn（dashscope）	主机、密钥、定价
siliconflow（.com）	siliconflow-cn（.cn）	主机、密钥、定价
stepfun（api.stepfun.ai）	stepfun-cn（api.stepfun.com）	主机、密钥、定价
zai（api.z.ai）	glm（open.bigmodel.cn）	主机、密钥、定价

kosha routes <model> 会列出提供某个模型的所有区域，方便你直接比较各区域的价格。

如果没有密钥，提供商会先回退到 models.dev + LiteLLM 公共目录；如果无法访问这些目录，则回退到 kosha 自己每周更新的快照，再回退到精选静态列表，因此在新机器上也能运行 kosha list。如果提供了密钥但密钥被拒绝，也会使用相同的回退流程：提供商仍会从公共目录中列出，状态显示为未认证，错误信息则保留供 kosha doctor 使用。准确的环境变量名称请参阅：docs/credentials.md。

非聊天模式

大多数模型都是 chat，但 mode 还涵盖 embedding、image、video、 audio、moderation、rerank 和 judgment。judgment 模型——TypeSafe 的 System One 系列——会用类型化的值回答问题（选项及其概率分布、一个概率，或按所述等级给出的分数），而不是生成文本。它有意不具备 chat 能力：将提示词路由给它属于类别错误。

kosha cheapest --role judgment    # rank judgment models by price
kosha model jev                   # mode: judgment, $0.042/M in, $0 out

工作原理

1. 发现——每个提供商各有一个发现器并发运行（Promise.allSettled）；每个发现器都会返回经过规范化的 ModelCard。失败的提供商会记录在 discoveryErrors() 中，不会阻塞其他提供商。
2. 补充信息——当提供商 API 未发布定价、上下文窗口和输出上限时，会从 models.dev 和 LiteLLM 补充；每张卡片上的 pricingSource 会注明来源。如果目录中有发布信息，卡片也会包含 releaseDate 和生命周期 status。
3. 弹性——每个提供商都有带指数冷却时间的熔断器，并支持过期缓存回退，因此提供商中断时会降级为使用缓存数据，而不是报错。
4. 缓存和清单——结果会缓存到 ~/.kosha/cache/（TTL 为 24 h），并导出为版本化快照，存放在 ~/.kosha/registry.json，供其他工具读取。
5. 代理——根据注册表解析请求的模型或 kosha:<strategy>[filters] 选择器，对候选路由进行排序，转发请求并支持故障转移，还会将预估成本和核算后的成本记录到 ~/.kosha/ledger-YYYY-MM.jsonl。

详情请参阅：docs/architecture.md、docs/resilience.md。

开发

pnpm install
pnpm run build        # compile to dist/
pnpm run typecheck    # tsc --noEmit
pnpm run lint         # biome lint
pnpm test             # vitest run
pnpm run check        # lint + build + test

pnpm aliases:check snapshot.json        # built-in aliases that are dead or a generation behind
pnpm snapshot:diff old.json new.json    # what changed between two snapshots

src/aliases.ts 中的别名表是目录中唯一手动编写的部分。aliases:check 会将其与快照进行比较，每周运行的快照任务也会标注比较结果，因此像 opus 这样过时的裸别名会在这里显现，而不是等到有人提交错误报告。

项目结构

src/
  cli.ts                 # CLI entry point and arg parsing
  cli-commands.ts        # command implementations (+ cli-cmd-*.ts for the larger ones)
  registry.ts            # ModelRegistry public API
  registry-runtime.ts    # discovery orchestration, enrichment, cache, manifest export
  registry-query.ts      # model / role / capability queries
  registry-selection.ts  # cheapest candidates, binding hints
  registry-routing.ts    # cheapest / fastest / reliable / balanced ranking
  discovery/             # one discoverer per provider + static and public-seed catalogs
  enrichment/            # models.dev + LiteLLM pricing enrichment
  credentials/           # credential resolution (env, CLI files, ADC, OAuth)
  provider-catalog.ts    # provider descriptors: base URLs, transport, env var names
  aliases.ts             # built-in short names → canonical model IDs
  claude-generation.ts   # which Claude generation accepts which API parameters
  model-features.ts      # tool dialect / structured-output inference per model
  proxy.ts               # OpenAI-compatible proxy: routing, failover, ledger
  wire-anthropic.ts      # OpenAI ↔ Anthropic request / response / SSE translation
  cost.ts                # spend ledger, budget gates, usage reconciliation
  tally.ts               # zero-dependency token usage + USD tally (also exported as ./tally)
  server.ts              # Hono HTTP API + operator token gate
  mcp-server.ts          # MCP stdio server
  types.ts               # shared types

添加提供商

对于 OpenAI 兼容的提供商（大多数提供商都属于此类），只需添加两条表项：

1. 在 src/provider-catalog.ts 的 PROVIDER_CATALOG 中添加描述符（id、基础 URL、传输方式、凭据环境变量）。
2. 在 src/discovery/generic-openai.ts 的 GENERIC_OPENAI_PROVIDERS 中添加规格。它会注册自己的发现器，根据描述符中的 credentialEnvVars 解析凭据，并在没有密钥时回退到公共目录。
3. 在 src/discovery/modelsdev-seed.ts 和 litellm-seed.ts 中，将提供商映射到其 models.dev / LiteLLM 标识，以便无密钥发现正常工作。请检查标识——GLM 的发布标识是 zhipuai，缺少映射会导致完全无法发现无密钥模型。
4. 在 test/discovery/generic-openai.test.ts 中添加一个用例，并在 docs/credentials.md 中记录环境变量。

只有在分类确实需要代码时，才编写发现器类——例如按路由定价（OpenRouter）、非 OpenAI 响应封装（TypeSafe）或来源重映射（Vercel）：

1. 创建 src/discovery/<provider>.ts，继承 BaseDiscoverer 或 OpenAICompatibleDiscoverer；其中已提供 fetchJSON 和 makeCard。
2. 在 src/discovery/index.ts 中导出该类，并在 DISCOVERER_REGISTRY 中添加工厂条目。
3. 仅当需要定制搜索顺序（CLI 文件、OAuth、ADC、SSO）时，才在 src/credentials/resolver.ts 中添加解析分支。环境变量中的普通 API 密钥无需添加分支——描述符已能处理。
4. 添加 test/discovery/<provider>.test.ts（模拟 fetch；请参阅 typesafe.test.ts）。

文档

凭据	每个提供商的环境变量、CLI 工具和配置文件
CLI	命令、标志和示例
HTTP API	端点、参数和响应架构
MCP 服务	工具、协议协商和客户端设置
配置	别名、路由、增强和编程式配置
架构	发现流程、模块图和添加提供商
弹性	熔断器、陈旧缓存和健康状况
运维	部署规格、指标、支出账本和恢复方案
安全	威胁目录、运行时扫描和提交前钩子
Discovery Plane v1	稳定的守护进程契约（增量、SSE 监视、绑定提示）

这些页面也同步到了 wiki，其中还有仅在 wiki 中提供的指南（故障排查、发布操作手册）。docs/ 是内容源：每次推送到 main 时都会重新生成镜像，因此请在这里编辑，而不是在 wiki 中编辑。

发布

1. 更新 package.json 和 server.json 中的 version（两处都要改），并为 CHANGELOG.md 中的 [Unreleased] 部分填写日期；将这些更改作为 PR 合并。
2. 创建标签并推送：

git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z
gh workflow run release-npm.yml -f tag=vX.Y.Z

工作流会检查标签是否与 package.json 中的版本一致，运行 lint / build / test，通过来源证明发布到 npm，并创建 GitHub Release。如果此仓库和工作流已在 npmjs.com 配置为可信发布者，发布时会通过 npm 可信发布（OIDC）进行身份验证；否则会使用仓库密钥 NPM_TOKEN。

支持

kosha 免费且开源。如果它能帮助你选择更便宜的模型，可以考虑赞助其维护：

• GitHub Sponsors
• Buy Me a Coffee

许可证

MIT