LLM Pricing

LLM 定价 MCP 服务

大多数 LLM 定价工具都只是静态查询表。本工具会将自身的价格数据与实时、独立维护的价格注册表进行核对，并在数据不一致时提醒你；它会根据成本 和 质量为任务选择模型，而不只是报出价格；还会追踪你的实际支出，而不只是可能产生的费用。这些功能由 RESTful API（FastAPI）、通过 STDIO 和 HTTP 提供的 29 个 MCP 工具、对话式 Agent + RAG 工作流、基于浏览器的 UI，以及自助式账单仪表板提供支持，覆盖 31 家主要 LLM 提供商的定价数据。

在线地址：https://llm-pricing-api.fly.dev

---

为什么选择它

• 价格可核验，而不只是盲目信任 — check_price_drift 和 get_data_quality 会将每项整理后的价格与实时外部注册表进行比较；如果价格偏差超过 5%，就会将其屏蔽（绝不会悄悄提供），并用一个 confirmed_pct 信任评分概括整个目录。
• 会为任务选择模型，而不只是报价 — recommend_model 和 optimize_workload 会根据你实际任务的成本 和 质量选择模型；如果更便宜的选项会牺牲质量，它会明确指出，而不是悄悄推荐。
• 追踪实际支出，而不只是可能产生的费用 — record_usage、analyze_session_usage 和 import_session_usage 可记录并分析真实支出，包括补录未设置实时用量追踪的编码 Agent 会话。
• 不止是 MCP 服务 — 同一套定价引擎还支持 REST API、基于浏览器的 UI（计算器、并排对比、历史记录/趋势）以及自助式账单仪表板。

---

功能

MCP 接口（STDIO + HTTP）

• 29 个 MCP 工具：get_all_pricing、estimate_cost、compare_costs、predict_cost、optimize_workload、recommend_model、check_price_drift、get_data_quality、get_performance_metrics、get_use_cases、get_ide_pricing、get_telemetry、get_pricing_history、get_pricing_trends、register_price_alert、list_price_alerts、delete_price_alert、get_pricing_export_url、list_conversations、delete_conversation、ask_agent、record_usage、get_usage_summary、register_budget_alert、list_budget_alerts、delete_budget_alert、get_cache_stats、analyze_session_usage、import_session_usage
• get_all_pricing、estimate_cost、compare_costs、get_use_cases 和 recommend_model 支持可选的 currency / country 参数（v1.76.0），并会添加换算后的 local_* 数值以及 currency_conversion 数据块；省略这两个参数时，输出保持不变
• STDIO 传输 — 通过 STDIO 使用 JSON-RPC 2.0，供本地 Claude Desktop 集成
• HTTP 传输 — POST /mcp（通过 HTTP 使用 JSON-RPC 2.0），供远程 MCP 客户端使用——无需本地安装
• MCP 协议版本：2024-11-05

RESTful API

• 从 31 家提供商获取实时价格（600 多种模型），支持异步获取和智能缓存。每个价格都会注明来源：经提供商价目表确认时，price_source_kind 为 provider；取自参考价格注册表时为 registry（并附带 registry_key 和日期）。注册表来源的模型可用于估算和比较，但绝不会计为经提供商确认；每周的 pickup PR 会自动为已覆盖的提供商添加新的注册表模型
• 成本估算：单个模型（POST /cost-estimate）和批量比较（POST /cost-estimate/batch）
• 按你的货币显示价格（v1.76.0）：GET /pricing、POST /cost-estimate、POST /cost-estimate/batch、GET /use-cases、POST /router/recommend 和 GET /pricing/public 接受 currency / country（查询参数或 X-Currency / X-Country 标头），并在未更改的 USD 数值旁以附加的 local_* 字段返回换算后的数值；浏览器计算器和比较页面会根据访问者所在国家预设货币，也允许切换 — 参见货币和区域设置
• 性能指标、用例推荐、价格历史记录和趋势
• 路由器推荐（POST /router/recommend），带反馈循环；GET /cache-stats 会报告其约 5 分钟推荐缓存在进程生命周期内的命中 / 未命中统计
• 实际用量 / 支出跟踪（POST /usage、GET /usage/summary）——与 /cost-estimate 对应的实际成本跟踪；为事件添加 session_id 标签，并按需分析单个会话（GET /usage/session/{session_id}），以获得基于实际数据的推荐和预估节省金额
• 兼容 OpenAI 的代理（POST /v1/chat/completions），可直接集成 SDK
• 调度网关（v1.77.0）：为同一端点添加 dispatch 策略和你自己的提供商密钥，即可实际调用最符合条件的模型 — 故障转移绝不会低于质量底线；提供包含所选模型、原因、实际成本和节省金额的回执、预算硬性限制、影子 A/B 测试，以及按组织范围导出的审计记录 — 参见调度网关
• 价格变化和预算支出阈值的 Webhook 警报（POST /usage/alerts，使用 HMAC-SHA256 签名；达到 hard_stop: true 阈值后，也会阻止该组织进行调度）
• 交互式文档：/docs（Swagger）和 /redoc

仓库成本审计器（scripts/audit_repo.py）

• 静态扫描 Python 代码库中的 LLM SDK 调用点（OpenAI、Anthropic、Google、LangChain），无需凭据，也不会对你的代码发起网络调用
• 使用与 predict_cost 相同的定价数据和 token 计算方式，估算每个调用点的成本
• 推荐更便宜的模型、提示词缓存、Batch API（适用于循环中的调用或看起来是离线处理的路径）以及基于任务的模型规格调整（在简单任务中使用旗舰模型）；还会标记多个调用点重复使用同一提示词的情况 — 参见 python scripts/audit_repo.py --help
• 仅提供静态估算（假设每月调用次数可配置）——部署后可结合 POST /usage 记录的实际支出，获取真实数据

AI 原生 SDLC 流水线（/release-feature，供使用 Claude Code 的贡献者使用）

• 通过专用阶段 Agent 处理功能请求，而不是让一个 Agent 一次性完成所有工作：规范 → 设计 → 编码 → 审查 → 测试与发布
• 规范确定功能做什么（需求、验收标准、非目标），不包含任何实现细节；在固定规范的基础上，设计确定如何构建（方案、版本递增、分支名称）——两个阶段都不会重新推导对方的决策
• 审查会针对差异内容并行派出三个 Agent（正确性、安全性、简化）；测试与发布会依据规范的验收标准检查结果、分流审查发现的问题、运行此仓库的完整发布检查清单，并且是唯一会提交、推送和创建 PR 的阶段
• 定义于 .claude/agents/phase-*.md（五个阶段 Agent）和 .claude/workflows/release-feature.js（Code→Review→Test 编排器）中——参见 CLAUDE.md 的“AI 原生 SDLC 流水线”章节
• 最终会创建一个面向 develop 的开放 PR；是否合并仍由人工决定

Agent + RAG 流水线

• 可配置的 LLM 后端：OpenAI GPT-4o-mini（默认）或通过环境变量配置的 Anthropic Claude
• ReAct 循环 Agent，可使用 29 个 MCP 工具中的 26 个（不包括 ask_agent、get_telemetry 和 get_cache_stats）
• 基于定价文档的 TF-IDF RAG，支持 top-k 检索
• 对话记忆：按会话使用 SQLite 持久化，轮次上限可配置
• /chat 上的 聊天 UI——实时流式显示 ReAct 进度
• POST /agent/chat — 阻塞式 JSON 响应
• POST /agent/chat/stream — SSE 流（thinking / tool_call / tool_result / answer / done）

浏览器 UI

路径	描述
/	营销落地页
/chat	对话式 AI Agent
/calculator	交互式成本计算器
/compare	并排模型对比
/history	定价历史图表（Chart.js）
/trends	价格变化排行榜
/widget	可嵌入的定价表
/billing	自助注册 + 升级仪表板
/conversations	对话历史查看器
/admin	服务统计、速率限制、客户
/mcp-setup	MCP 集成中心
/api-docs	API 参考（Swagger/ReDoc）
/whats-new	版本说明时间线

所有 UI 都采用一致的深色设计系统（CSS 变量、'Segoe UI' 字体、#0f1117 背景、#7c6af7 强调色），完全适配移动设备，并带有固定的汉堡导航栏。

SaaS 计费（Stripe）

• 免费层级注册：POST /billing/signup（邮箱 → API 密钥，无需 Stripe）
• 付费层级（Pro/Enterprise）通过 Stripe Checkout 办理 → 自动更新速率限制
• 自助服务门户：GET /billing/portal
• 使用情况仪表板：GET /billing/me（路由器调用次数、节省金额、接受率）
• Stripe webhook 处理程序：POST /billing/webhook

API 密钥层级与速率限制

• 免费：30 req/min · Pro：120 req/min · Enterprise：600 req/min
• 层级取自计费数据库（客户 API 密钥）；或者，仅当请求也携带有效的全局 MCP_API_KEY 时，才取自 X-Api-Key-Tier 标头——匿名请求始终使用默认配额，因此不能通过该标头自行选择更高的限制
• GET /rate-limits/tiers — 列出层级详情的公共端点

安全与质量

• 大多数端点均为公开端点（只读定价数据、界面、MCP 工具）
• 受保护的端点（/billing/me、/router/recommend、/router/feedback、/billing/portal）需要计费 API 密钥或全局 MCP_API_KEY
• /v1/chat/completions 的调度模式需要免费层级的客户密钥（全局 MCP_API_KEY 会被拒绝——调度会写入每个组织的账本）；提供方密钥由用户按请求自行提供（通过 X-Provider-Key-* 标头），仅临时使用，绝不会存储、记录或回显；提示词和补全内容也不会被存储、记录或回显
• 按客户端 IP 和层级类别进行速率限制——包括匿名的 /agent/chat 和 /agent/chat/stream 端点（无需 API 密钥，但会受到限流，因为每次调用都会使用运营方的密钥运行一个大模型）
• 请求大小限制（默认 1MB）
• 1870 项测试通过，每个 PR 均运行 CI/CD（测试 → lint → bandit → OSV → gitleaks → 部署）

部署

• 主要部署：Fly.io — shared-cpu-1x、512MB，每月约 $3.40
• CI/CD：GitHub Actions — 在 master 推送时测试 → 部署
• 支持蓝绿部署，可优雅关闭（SIGTERM/SIGINT）
• 健康探测：/health、/health/live、/health/ready、/health/detailed

---

目录

• 快速开始（Claude Desktop）
• 快速开始（API）
• HTTP MCP 传输
• API 参考
• 配置
• 开发
• 测试
• 部署
• 贡献
• 路线图

---

快速开始（Claude Desktop）

上方的一键链接会直接打开 Cursor/VS Code（尽力而为——深层链接支持情况因客户端版本而异）。其他客户端都使用下方的复制粘贴配置，该配置始终有效。

选项 A — 远程（无需安装）

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "llm-pricing": {
      "url": "https://llm-pricing-api.fly.dev/mcp"
    }
  }
}

重启 Claude Desktop。全部 29 个定价工具将立即可用。

选项 B — 通过 npx 使用 STDIO（无需克隆，无需 Python）

适用于仅支持基于 command 的 STDIO 服务的客户端（不支持直接远程/HTTP 配置）。此方式会运行一个零依赖的 npm 包，将标准输入/输出桥接到上方的托管服务——无需克隆，无需 Python，也无需 pip install。

{
  "mcpServers": {
    "llm-pricing": {
      "command": "npx",
      "args": ["-y", "llm-pricing-mcp"]
    }
  }
}

重启 Claude Desktop。配置选项（自托管、超时）请参阅 npm/llm-pricing-mcp/README.md。

选项 C — 本地 STDIO，完全离线

1. 克隆并安装：

git clone https://github.com/skakumanu/llm-pricing-mcp-server.git
cd llm-pricing-mcp-server
python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. 添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "llm-pricing": {
      "command": "python",
      "args": ["/absolute/path/to/mcp/server.py"],
      "cwd": "/absolute/path/to/llm-pricing-mcp-server",
      "env": { "PYTHONUNBUFFERED": "1" }
    }
  }
}

详细设置说明、Windows 路径和故障排除请参阅 docs/CLAUDE_INTEGRATION.md。

---

快速开始（API）

运行服务

python src/main.py
# or
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

公开端点（无需身份验证）

# Get all pricing
curl http://localhost:8000/pricing

# Estimate cost
curl -X POST http://localhost:8000/cost-estimate \
  -H "Content-Type: application/json" \
  -d '{"model_name": "gpt-4o", "input_tokens": 1000, "output_tokens": 500}'

# Chat with the agent
curl -X POST http://localhost:8000/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the cheapest model for RAG pipelines?"}'

# OpenAI-compatible routing proxy
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]}'

受保护的端点（需要计费 API 密钥或 MCP_API_KEY）

# Get your API key via free signup
curl -X POST http://localhost:8000/billing/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

# Use the returned api_key for protected endpoints
curl -H "x-api-key: <your-api-key>" \
  http://localhost:8000/billing/me

curl -X POST http://localhost:8000/router/recommend \
  -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"max_cost_per_1m_tokens": 5}'

Agent 流式传输

curl -X POST http://localhost:8000/agent/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Compare GPT-4o vs Claude Sonnet pricing"}' \
  --no-buffer

事件：thinking → tool_call → tool_result → answer → done

---

HTTP MCP 传输

该服务在 POST /mcp 提供 JSON-RPC 2.0 端点，通过 HTTP 支持 MCP 协议（协议版本 2024-11-05）。

支持的方法

方法	描述
initialize	握手——返回服务信息和功能
initialized	通知——返回 204
tools/list	列出全部 29 个工具及其输入架构
tools/call	执行工具

示例

# List tools
curl -X POST https://llm-pricing-api.fly.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a tool
curl -X POST https://llm-pricing-api.fly.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 2, "method": "tools/call",
    "params": {
      "name": "estimate_cost",
      "arguments": {"model_name": "gpt-4o", "input_tokens": 1000, "output_tokens": 500}
    }
  }'

GET /mcp 会返回服务信息和配置片段。完整交互式文档请访问 /docs（Swagger UI）和 /redoc。

---

API 参考

公开端点

方法	路径	描述
GET	/	落地页（HTML）
GET	/pricing	所有模型定价（?provider= 筛选；?currency= / ?country= 可添加 local_prices）
GET	/locale	此请求解析出的货币/国家/地区（浏览器预设；绝不回显 IP）
GET	/currency/rates	内置的 USD 汇率表（截至日期、7 天过期标记）
GET	/models	所有可用模型
GET	/performance	吞吐量、延迟、上下文窗口、质量评分
GET	/use-cases	模型用例建议
GET	/telemetry	服务使用指标和分析数据
GET	/admin/stats	汇总的服务统计信息
GET	/admin/rate-limits	当前速率限制状态
GET	/rate-limits/tiers	API 层级定义
GET	/pricing/history	历史定价快照
GET	/pricing/trends	价格变动排行榜
GET	/pricing/public	公开定价（无需身份验证，可安全嵌入）
GET	/pricing/history/export	CSV/JSON 导出
POST	/cost-estimate	单个模型成本估算
POST	/cost-estimate/batch	多模型成本比较
POST	/agent/chat	阻塞式 Agent 聊天
POST	/agent/chat/stream	流式 Agent 聊天（SSE）
GET	/agent/conversations	列出对话
DELETE	/agent/conversations/{id}	删除对话
GET	/api/versions	API 版本信息
GET	/pricing/alerts/signing-info	Webhook 签名密钥信息
POST	/v1/chat/completions	兼容 OpenAI 的路由代理（仅提供建议；下方的 dispatch 模式需要客户密钥）
GET	/dispatch/providers	可执行的提供商、其密钥标头，以及可调度的模型（及不可调度的原因）
GET	/mcp	HTTP MCP 服务信息
POST	/mcp	HTTP MCP JSON-RPC 2.0
POST	/billing/signup	免费层级注册 → API 密钥
GET	/billing	账单仪表板（HTML）
POST	/billing/webhook	Stripe webhook
GET	/health	健康检查
GET	/health/live	Kubernetes 存活探针
GET	/health/ready	Kubernetes 就绪探针
GET	/health/detailed	包含服务状态的详细健康信息

受保护端点（账单 API 密钥或 MCP_API_KEY）

方法	路径	描述
POST	/router/recommend	智能模型路由建议
POST	/router/recommend/stream	流式路由器（SSE）
POST	/router/feedback	提交路由反馈
GET	/telemetry/savings	路由器节省费用报告
POST	/usage	记录一条实际使用事件（由服务端计算成本）
POST	/usage/batch	一次记录多个使用事件
GET	/usage/summary	按模型/提供商统计各组织的实际支出摘要
POST	/v1/chat/completions + dispatch	调度模式（仅限客户密钥）：使用你的 X-Provider-Key-* 执行最合适的可用模型，支持故障转移并生成回执
GET	/dispatch/receipts	导出组织调度回执的纯元数据 JSON/CSV（仅限客户密钥）
POST	/billing/checkout	Stripe Checkout 会话
GET	/billing/portal	Stripe 账单门户
GET	/billing/me	使用情况仪表板
POST	/pricing/alerts	注册价格变动 webhook
GET	/pricing/alerts	列出提醒
DELETE	/pricing/alerts/{id}	删除提醒

请求/响应示例

POST /cost-estimate

// Request
{"model_name": "gpt-4o", "input_tokens": 1000, "output_tokens": 500}

// Response
{
  "model_name": "gpt-4o", "provider": "OpenAI",
  "input_tokens": 1000, "output_tokens": 500,
  "input_cost": 0.0000025, "output_cost": 0.000005,
  "total_cost": 0.0000075, "currency": "USD"
}

POST /billing/signup

// Request
{"email": "[email protected]"}

// Response
{
  "api_key": "abc123...", "org_id": "org-xyz...",
  "tier": "free", "message": "Welcome! Your free API key is ready."
}

POST /router/recommend

// Request (x-api-key header required)
{"max_cost_per_1m_tokens": 5, "task_type": "code"}

// Response
{
  "recommended": {"model_name": "gpt-4o-mini", "provider": "OpenAI", ...},
  "alternatives": [...],
  "reason": "Best quality/cost ratio for code tasks under $5/1M tokens",
  "routing_id": "uuid4..."
}

---

货币和区域设置

API 提供的所有价格均为 USD 标价。自 v1.76.0 起，价格列表、单次和批量成本估算、用例、路由器推荐和公开价格端点也可以在显示 USD 原价的同时，以 13 种货币显示各项金额：USD、EUR、GBP、INR、JPY、CAD、AUD、BRL、CNY、SGD、CHF、KRW、MXN：

curl "http://localhost:8000/pricing?currency=EUR"            # every model gains local_prices
curl -H "X-Country: IN" "http://localhost:8000/pricing/public" # INR via the country
curl -X POST "http://localhost:8000/cost-estimate?country=JP" \
  -H "Content-Type: application/json" \
  -d '{"model_name": "gpt-4o", "input_tokens": 1000, "output_tokens": 500}'

• 输入和优先级：currency 查询参数 > X-Currency 请求头 > country 查询参数 > X-Country 请求头 > 平台地理位置请求头（CF-IPCountry、X-Vercel-IP-Country、CloudFront-Viewer-Country、X-Country-Code）> 尽力进行的 IP 查询 > USD。明确指定的货币始终优先于指定的国家/地区（此时国家/地区只用于标记响应）。
• 结构：换算后的金额以附加字段形式提供：local_prices（按模型）、local_cost、local_cost_range，以及一个 currency_conversion 块（currency、rate、rate_as_of、rate_age_days、rate_is_stale、rate_source、country、country_source、currency_source、fallback_to_usd、fallback_reason、note）。USD 字段永不改名或换算；若没有明确指定或检测到任何信息，则不会出现任何新增字段。
• 拒绝与回退：明确请求 13 种支持货币以外的代码时，返回 400，响应正文会列出支持的货币（不会静默回退到 USD）。若某国家/地区所用货币不受支持，则使用 USD，并设置 fallback_to_usd: true、fallback_reason: "country_not_mapped"。
• 汇率：汇率来自随代码提供的表格 data/exchange_rates.json，每周由 scripts/refresh_exchange_rates.py 更新，并通过人工合并 PR 纳入（数据来自 Frankfurter，后备数据源为 ECB 参考汇率）。请求期间不会获取任何数据。超过 7 天的汇率仍会提供，但会标记为 rate_is_stale: true；GET /currency/rates 会公开该表格、其 as_of 日期，以及它是否仍为编写时的占位数据。换算金额仅供参考——服务提供商以 USD 计费。
• 浏览器：/calculator 和 /compare 页面会显示货币选择器，默认选中检测到的国家/地区所用货币（未检测到时为 USD）；更改后会重新渲染所有金额。选择会在页面和重新加载后保留（存储于 localStorage 中的 llmp.currency）。落地页只显示选择器和说明。
• 隐私：客户端 IP 仅用于临时解析国家/地区，不作其他用途——此功能绝不会存储或记录该 IP，也不会在任何响应中包含该 IP。响应中可能回传的仅为解析出的 ISO 国家/地区代码。所有人看到的模型及其顺序相同；成本等级仍以 USD 区间表示。
• MCP：get_all_pricing、estimate_cost、compare_costs、get_use_cases、recommend_model 接受可选的 currency 和 country 参数。MCP 不会检测位置。

调度网关

自 v1.77.0 起，兼容 OpenAI 的端点可以根据推荐执行请求。发送 dispatch 策略、免费套餐服务密钥和你自己的提供商密钥，即可实际调用最符合条件的模型；你会收到标准的 chat.completion，其中包含实际的 usage 和 dispatch_receipt。如果不提供 dispatch，该端点仍和以往一样，只提供推荐的代理服务。

import os
from openai import OpenAI

SERVICE_KEY = os.environ["LLM_PRICING_SERVICE_KEY"]   # your free-tier key from POST /billing/signup

client = OpenAI(
    base_url="https://llm-pricing-api.fly.dev/v1",
    api_key=SERVICE_KEY,
    default_headers={                      # bring your own provider keys — used transiently, never stored
        "X-Provider-Key-OpenAI": "...",
        "X-Provider-Key-Anthropic": "...",
        "X-Provider-Key-Google": "...",
    },
)
resp = client.chat.completions.create(
    model="gpt-4o",                        # what you would have used — the receipt reports savings against it
    messages=[{"role": "user", "content": "Summarise this ticket..."}],
    max_tokens=300,
    extra_body={"dispatch": {"objective": "cheapest", "min_quality_score": 70,
                             "max_request_cost_usd": 0.01, "request_id": "ticket-4812"}},
)
print(resp.choices[0].message.content)
receipt = resp.model_extra["dispatch_receipt"]
print(receipt["chosen"]["model"], receipt["cost"]["actual_usd"],
      receipt["savings"]["vs_requested_model"]["savings_usd"])

• 预设（dispatch.objective）：

  目标	选择规则
  balanced（默认）	路由器的质量/美元排序
  cheapest	满足所有约束的模型中，综合每百万单位成本最低者
  best_quality	质量评分最高者（评分相同则选择更便宜者）
  lowest_latency	已知延迟最低者（未知延迟者排在最后）
  pinned	仅选择 pinned_model；回执会报告相较于满足质量下限的最便宜模型，节省了多少成本
  硬性约束沿用路由器的词汇——min_quality_score、max_cost_per_1m_tokens、
  min_context_window、task_type、preferred_provider、exclude_reasoning_models——以及 allow /
  deny 列表（模型名称或 provider:<name>）和 max_request_cost_usd（提示词令牌数 × 输入价格 +
  max_tokens × 输出价格；设置上限时，该 max_tokens 值——由你指定，或服务器默认值 1024——也会
  发送给服务提供方，以确保上限确实能限制调用）。所有字段均为可选；空的
  dispatch: {} 表示采用均衡策略并启用故障转移。

• 资格条件：仅限价格已获服务提供方确认的模型（价格有偏差而暂不提供、从未定价及已停用的模型永远不会被调度）、属于可执行服务提供方的模型——OpenAI、Anthropic、Google（Gemini API）、 Groq、Together AI、Fireworks AI、DeepSeek、Mistral AI、xAI；其他模型仅供推荐——且你已提供其服务提供方密钥的模型。GET /dispatch/providers 会预先列出所有这些信息；回执会列出每项排除及其原因；若没有符合条件的模型，错误会在调用任何服务提供方之前指出排除模型的约束。

• 故障转移（dispatch.failover，默认开启，max_attempts 为 3，timeout_ms 为 30000）：发生超时、5xx、429、上下文过长或找不到模型时，会转到下一个仍满足所有约束的候选模型（上下文过长时，仅转到上下文窗口更大的模型）。如果故障转移会导致低于你的质量下限，则调度会失败——all_attempts_failed 会指出该下限。你自己的服务提供方密钥遇到 401/403 时会终止（provider_auth_failed，并指出服务提供方）。固定指定的模型不会触发故障转移。

• 回执：包含 chosen（模型、服务提供方、质量、综合价格、来源）、reason、candidates（按排名排列）、excluded + excluded_summary、usage、cost（actual_usd = 服务提供方令牌数 × 目录价格）、savings（vs_most_expensive_eligible、vs_requested_model，以及固定指定模型时的 forgone_vs_cheapest_meeting_floor）、latency（总耗时 / 服务提供方耗时 / 开销）、attempts、shadow、dispatch_id、request_id。在策略中添加 currency / country（或使用 X-Currency / X-Country），即可按你的货币返回 local 区块——仅接受明确指定的值；此端点绝不会推断所在地。

• 账本：每次成功调度都会记录且仅记录一条准确的使用事件（重试时由 request_id 去重——服务提供方调用本身不会去重）和一条标记为已使用的路由决策，因此 GET /usage/summary、GET /telemetry/savings、接受率和预算提醒都能反映实际调度支出。

• 预算硬性拦截：使用你的客户 API 密钥发送 POST /usage/alerts 并设置 hard_stop: true 后，如果某提醒周期内记录的支出达到其阈值，就会拒绝为你的组织执行调度，并返回 402 budget_hard_stop。提醒仅绑定到该密钥所属的组织（你无法停止、列出或删除其他组织的提醒），Webhook 仍会像之前一样触发；不关联组织的提醒仅发送通知。

• 影子 A/B 测试：shadow: {"model": "..."} 或 shadow: {"objective": "best_quality"} 会使用你自己的密钥并行运行第二个模型。你只会收到主模型的完成结果；回执会同时附上两个模型的成本、延迟和结果，以及它们之间的差值。影子模型失败不会导致请求失败；成本上限适用于主模型和影子模型的合计成本（如果影子模型会导致超出上限，则会跳过并在回执中说明）。影子模型的支出会被记录——这是真实费用。

• 审计导出：GET /dispatch/receipts?format=csv|json&since=&until=&outcome=&limit= 会以元数据行的形式返回你组织的回执（保留 90 天）。行中绝不会包含提示词、完成内容或密钥。

• 此版本的范围：非流式、纯文本、单选项聊天完成。stream: true、tools / functions / tool_choice、n > 1、非文本的 response_format 和图像内容部分都会在执行前被拒绝，并指出相应功能（不会静默丢弃任何内容；接受 user，但不会转发）。不新增 MCP 工具。池化的服务方付费密钥和按账户存储的密钥明确不在范围内。

• 隐私：服务提供方密钥仅存在于请求标头和发往服务提供方的调用中；提示词和完成内容仅存在于请求、服务提供方调用和 choices 中。任何级别都不会持久化或记录二者；服务提供方错误正文只会被归类为结果，不会被复制。服务提供方会直接向你收费。

配置

环境变量

# LLM Backend (Agent)
AGENT_LLM_PROVIDER=openai           # "openai" (default) or "anthropic"
AGENT_MODEL=gpt-4o-mini             # Model name
OPENAI_API_KEY=sk-...               # Required when AGENT_LLM_PROVIDER=openai
ANTHROPIC_API_KEY=sk-ant-...        # Required when AGENT_LLM_PROVIDER=anthropic

# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
DEBUG=false

# Security
MCP_API_KEY=your-strong-random-key  # Global admin key (optional — billing keys work too)
RATE_LIMIT_PER_MINUTE=60            # Default rate limit (overridden by tier)

# Local currency (v1.76.0)
CURRENCY_DETECTION_ENABLED=true     # false = never infer a country from the client IP
GEO_LOOKUP_TIMEOUT_SECONDS=1.0      # request-path cap on the IP -> country lookup
EXCHANGE_RATES_PATH=                # override for data/exchange_rates.json (Fly sets /app/vendored/exchange_rates.json)

# Dispatch gateway (v1.77.0) — provider keys are never configured here; callers bring their own per request
DISPATCH_ENABLED=true               # false = dispatch mode of /v1/chat/completions returns 503
DISPATCH_DEFAULT_MAX_TOKENS=1024    # used when the caller omits max_tokens (Anthropic requires one)
DISPATCH_ATTEMPT_TIMEOUT_MS=30000   # per-attempt provider timeout
DISPATCH_MAX_ATTEMPTS=3             # failover attempts (1 when failover is off or the model is pinned)
DISPATCH_RECEIPT_RETENTION_DAYS=90  # metadata-only receipt rows are purged past this age

# Billing (Stripe)
STRIPE_SECRET_KEY=sk_live_...       # Optional — free signup works without this
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID_PRO=price_...
STRIPE_PRICE_ID_ENTERPRISE=price_...
BILLING_DB_PATH=/app/data/billing.db
BILLING_BASE_URL=https://llm-pricing-api.fly.dev

切换 LLM 提供商只需更改环境变量，无需修改代码：

提供商	AGENT_LLM_PROVIDER	AGENT_MODEL	预估费用
OpenAI（默认）	openai	gpt-4o-mini	~$0.73/mo
OpenAI（高性能）	openai	gpt-4o	~$8/mo
Anthropic	anthropic	claude-sonnet-4-6	~$15/mo
Anthropic（快速）	anthropic	claude-haiku-4-5-20251001	~$2/mo

---

开发

项目结构

llm-pricing-mcp-server/
├── src/
│   ├── __init__.py                  # Version (1.48.0)
│   ├── main.py                      # FastAPI app + all endpoints
│   ├── config/settings.py           # Pydantic settings
│   ├── models/                      # Pydantic models (pricing, billing, router, …)
│   └── services/                    # Business logic
│       ├── pricing_aggregator.py    # Multi-provider pricing aggregator
│       ├── billing_service.py       # SQLite billing / customer DB
│       ├── router.py                # Model routing engine
│       ├── savings_tracker.py       # Router savings analytics
│       ├── benchmark_service.py     # Quality scores + HF API
│       ├── pricing_history.py       # Historical snapshot DB
│       └── …
├── mcp/
│   ├── server.py                    # STDIO JSON-RPC 2.0 server
│   └── tools/                       # 29 MCP tool implementations
│       ├── tool_manager.py
│       ├── get_all_pricing.py
│       ├── estimate_cost.py
│       └── …
├── agent/
│   ├── pricing_agent.py             # ReAct loop agent
│   ├── llm_backend.py               # OpenAI + Anthropic backends
│   └── tools.py                     # Agent tool wrappers
├── static/                          # Browser UIs (one dir per page)
│   ├── landing/                     # / (marketing page)
│   ├── chat/                        # /chat (agent UI)
│   ├── calculator/                  # /calculator
│   ├── compare/                     # /compare
│   ├── history/                     # /history
│   ├── trends/                      # /trends
│   ├── widget/                      # /widget
│   ├── billing/                     # /billing
│   └── admin/                       # /admin
├── tests/                           # 667 tests
├── docs/                            # Extended documentation
├── .github/workflows/ci-cd.yml      # CI/CD pipeline
├── Dockerfile
├── fly.toml                         # Fly.io deployment config
└── requirements.txt

添加新的提供商

1. 创建 src/services/<provider>_pricing.py，实现 BasePricingProvider
2. 在 src/services/pricing_aggregator.py 中注册
3. 在 src/config/settings.py 中为可选 API 密钥添加环境变量
4. 在 tests/ 中添加测试

---

测试

# Run all 667 tests
pytest

# With coverage
pytest --cov=src --cov-report=term-missing

# Specific suites
pytest tests/test_api.py -v
pytest tests/test_billing_endpoints.py -v
pytest tests/test_mcp_http.py -v     # HTTP MCP transport
pytest tests/test_router.py -v

测试文件

文件	覆盖内容
test_api.py	核心 API 端点
test_agent_endpoint.py	Agent 聊天与流式传输
test_billing_endpoints.py	注册、结账、Webhook、个人信息
test_billing_service.py	BillingService 单元测试
test_mcp_http.py	HTTP MCP 传输
test_router.py	路由器推荐与反馈
test_security.py	身份验证中间件
test_admin_dashboard.py	管理端点
test_history_tools.py	定价历史与趋势
test_rag.py	TF-IDF RAG 流水线
test_agent.py	ReAct Agent 单元测试
test_currency.py	货币服务：映射、优先级、过期状态、舍入、汇率表
test_currency_api.py	六个端点上的 REST 区域设置解析、/locale、/currency/rates、隐私
test_currency_mcp.py	五个 MCP 工具中的 currency / country
test_currency_ui.py	共享浏览器货币控件
test_refresh_exchange_rates.py	每周汇率表刷新脚本与工作流任务
test_dispatch_executors.py	通过 httpx.MockTransport 测试提供商执行器：线路转换、用量/完成状态映射、错误分类
test_dispatch_service.py	分派策略、资格、排序、故障转移、上限、硬停止、影子 A/B、凭据（伪执行器）
test_dispatch_api.py	HTTP 上的分派模式：身份验证、不支持的功能、账本、预算提醒、导出、密钥/提示词泄露哨兵

---

部署

Fly.io（主要）

应用部署在 Fly.io，每次推送到 master 时都会自动部署。

# Install flyctl
# https://fly.io/docs/getting-started/installing-flyctl/

# Deploy manually
flyctl deploy

# Set secrets
flyctl secrets set \
  MCP_API_KEY=... \
  OPENAI_API_KEY=... \
  AGENT_LLM_PROVIDER=openai \
  AGENT_MODEL=gpt-4o-mini

# Set Stripe secrets (optional — free tier works without)
flyctl secrets set \
  STRIPE_SECRET_KEY=sk_live_... \
  STRIPE_WEBHOOK_SECRET=whsec_... \
  STRIPE_PRICE_ID_PRO=price_... \
  STRIPE_PRICE_ID_ENTERPRISE=price_... \
  BILLING_BASE_URL=https://llm-pricing-api.fly.dev

配置位于 fly.toml。/app/data/ 下的持久化卷存储所有 SQLite 数据库。

GitHub Actions CI/CD

.github/workflows/ci-cd.yml 流水线：

1. 每次 PR 都运行全部 667 项测试
2. 推送到 master 时部署到 Fly.io（通过 FLY_API_TOKEN 密钥）
3. 部署后执行健康检查

健康检查端点

GET /health        → {"status":"healthy","version":"1.39.0"}
GET /health/live   → {"alive":true}
GET /health/ready  → {"ready":true,"checks":{...}}
GET /health/detailed → detailed environment + service statuses

蓝绿部署

支持优雅关闭并排空请求。请参阅 docs/BLUE_GREEN_DEPLOYMENT.md。

---

实时数据

服务器通过网页抓取并使用智能缓存，从官方公开定价页面获取定价数据。获取定价数据无需提供商 API 密钥。

• 缓存 TTL：定价数据为 2 小时，性能指标为 5 分钟
• 回退：实时数据源不可用时使用静态硬编码数据
• 提供商：OpenAI、Anthropic、Google、Cohere、Mistral AI、Groq、Together AI、Fireworks AI、Perplexity AI、AI21 Labs、Anyscale、Amazon Bedrock

可选的提供商 API 密钥（OPENAI_API_KEY、ANTHROPIC_API_KEY 等）可提高模型列表的新鲜度，但并非必需。

---

贡献

请参阅 docs/CONTRIBUTING.md。本仓库采用 Git Flow：

feature/<name>  →  develop (PR)  →  master (PR)  →  Fly.io auto-deploy

• 切勿直接提交到 develop 或 master
• 分支名称：feature/<topic>-v<version>（例如 feature/stripe-billing-v1.37.0）
• 针对 develop 创建 PR；维护者会在发布时将 develop 合并到 master

---

许可证

MIT——请参阅 LICENSE。

---

路线图

已完成

• v1.39.0 — OpenAPI 标签 + 分组式 Swagger UI；第 15 个 MCP 工具（ask_agent）
• v1.38.6 — MCP 服务修复：初始化所有服务，注册 ask_agent 工具，初始化 PricingAlertService
• v1.38.5 — 落地页 MCP 集成指南（Claude Desktop、VS Code、Cursor）
• v1.38.4 — 计费测试版体验：即将推出文案、禁用付费按钮、优雅处理 503
• v1.38.3 — 聊天和对话页面采用深色主题 + 共享导航
• v1.38.2 — 所有 9 个 UI 统一设计系统（以管理界面为规范参考）
• v1.38.1 — 统一 UI 主题
• v1.38.0 — HTTP MCP 传输（POST /mcp、GET /mcp），支持远程客户端
• v1.37.3 — 适配移动设备的 UI，所有页面采用统一导航
• v1.37.2 — 在 Fly.io 卷挂载时自动创建 SQLite 目录
• v1.37.1 — 在 / 提供营销落地页
• v1.37.0 — Stripe SaaS 计费：免费注册、Pro/Enterprise 套餐、自助服务门户
• v1.36.0 — API 密钥套餐（免费/Pro/Enterprise）、路由器反馈循环、流式路由器、迁移至 Fly.io
• v1.35.0 — 质量价值指数、基准测试服务、模型路由器、节省费用追踪器
• v1.33.0 — 将默认大模型后端切换为 GPT-4o-mini（成本降低约 20 倍）
• v1.27.0–v1.32.0 — 管理仪表板、小组件、对比 UI、计算器、价格提醒、历史记录导出
• v1.10.0–v1.26.0 — Agent + RAG 流水线、流式处理、对话记忆、价格历史记录
• v1.5.1 — 12 个提供商、87+ 个模型、实时数据获取
• v1.6.0 — 完整 MCP 协议（STDIO JSON-RPC 2.0）、Claude Desktop 集成

即将推出

• 上线 Stripe 产品（配置产品 + 设置 Fly.io 密钥）
• 关闭 Azure App Service（目前并行运行，每月约 27 美元）
• 自定义域名
• 添加其他大模型后端（Groq 直连、Ollama 本地）
• 支持 WebSocket，以便实时订阅价格