Inferrail

了解 AI 工作的成本。
无需留存它说过的话。

Inferrail 是一个由你自行运行的网关，位于你的应用与 OpenAI 或 Anthropic 之间。 它会显示每项 AI 任务的成本，拦截会使任务超出支出限额的调用， 并且不会将提示词或响应复制到记录中。

快速开始 · 数据去向 · 工作原理 · 文档 · tryinferrail.com

Inferrail 网关与仪表板的一次真实运行，使用本地替代模型：无需 API 密钥，也不会产生服务提供方费用。录制方式

开发者预览版。 以下所有功能均已实现并经过测试。 CLI 标志、配置和收据字段在 1.0 版本发布前仍可能变更。

快速开始

需要 Python 3.11+。

在 Python 应用中保护一次运行。 无需配置文件，也无需 打开第二个终端：

pip install inferrail
export OPENAI_API_KEY=sk-...

import inferrail
from openai import OpenAI

base_url = inferrail.start()   # the gateway, on a background thread in this process
client = OpenAI(base_url=base_url, api_key="unused")
client.chat.completions.create(
    model="gpt-4o-mini",   # example: any model your account can use (`inferrail models` lists them)
    max_tokens=200,
    messages=[{"role": "user", "content": "Summarize this contract."}],
    extra_headers={
        "X-Inferrail-Attribute-Work-Id": "contract-review-42",   # the run
        "X-Inferrail-Budget-Usd": "0.50",                        # its dollar ceiling
    },
)

所有携带相同运行 ID 的调用都会共享该预算，包括并行调用。任何 会使运行超出预算的调用，都会在到达 OpenAI 前收到 HTTP 402。 然后：

inferrail work contract-review-42

即可查看这次运行的成本。

Inferrail 不会选择模型：你发送的模型 ID 会原样传递给 服务提供方。美元预算需要设置该模型的价格；inferrail models 会显示已有价格的模型，而 inferrail.start(pricing=...) 可为新模型添加价格。框架示例（LangChain、LangGraph、 OpenAI Agents SDK、CrewAI、Haystack、LlamaIndex、Microsoft Agent Framework）： 示例。

离线试用。 无需 API 密钥、不会发起网络调用，也不会产生服务提供方费用：

pip install inferrail
inferrail demo
inferrail report --by customer --receipts ./inferrail-demo-receipts.jsonl

该演示会将预设请求通过真实引擎发送到模拟服务提供方，使用标记为 DEMO 的虚构价格，并按客户打印费用明细 （录制）。

作为独立进程运行，并使用本地仪表板。 如果要让多个应用共用 一个网关，或实时监控调用，请在网关的终端中设置密钥：

export OPENAI_API_KEY=sk-...          # and/or ANTHROPIC_API_KEY
inferrail serve --quickstart --app-mode

打开它显示的 Dashboard: URL，然后将应用指向网关并为工作添加标签：

from openai import OpenAI

# api_key is a placeholder: your provider key stays in the gateway
client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="unused")
client.chat.completions.create(
    model="gpt-4o-mini",   # example model id; Inferrail passes yours through
    messages=[{"role": "user", "content": "Summarize this contract."}],
    extra_headers={
        "X-Inferrail-Attribute-Customer": "acme",
        "X-Inferrail-Attribute-Work-Id": "contract-review-42",
        "X-Inferrail-Budget-Usd": "0.50",   # optional: a dollar ceiling for this work
    },
)

调用会显示在实时动态中，工作页面会汇总 contract-review-42 的费用。Anthropic SDK 的用法相同，只需设置 base_url="http://127.0.0.1:8000"（不带 /v1）。更多客户端和 框架请参阅：docs/integrations.md。

python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install inferrail

• 每单位工作的成本。 使用任意属性标记调用（customer、 workflow、work_id 等）。仪表板和 inferrail report --by <tag> 会按这些标签汇总已知成本，inferrail work <id> 则显示单项任务。
• 单次 Agent 运行的美元预算。 在请求头中声明预算。并行 调用可安全共享预算，超出预算的调用会在到达服务提供商之前收到 HTTP 402 响应。还支持全局、项目、每日和每月 预算。配方。
• 实验性：为付费 Agent 提供相同预算。 如果任务还会通过 x402 购买 服务（付费 API、数据、其他 Agent），单个任务预算可同时覆盖模型调用和购买。子 Agent 会获得有上限的预算份额，不符合预算的购买 会在签名前被拒绝。付款方密钥不会暴露给 Agent。提供 Python 运行时，以及适用于 @x402/fetch 的 TypeScript 适配器。 示例（本地验证；不涉及主网）。
• 可信赖的数据。 只有在服务提供商报告用量且已有价格记录时，才会记录成本。否则标记为 unknown，绝不会猜测为 $0。
• 本地记录。 收据以 SQLite 或 JSONL 文件的形式保存在你的设备上。 无需 Inferrail 账户，也不涉及托管服务。
• 向 Agent 提问。 只读 MCP 服务可回答 “工作 contract-review-42 的成本是多少？” 之类的问题。

隐私边界

归因标签会按原样存储，因此请使用标识符，并避免在其中放入机密和消息内容。inferrail verify-payload-free 会打印实时收据架构，金丝雀测试则会检查消息 正文是否会进入收据。这两者都不属于安全审计。除非配置了端点，否则可选的 用量信标不会发送任何内容 （详情）。如何自行检查这些内容： docs/PRODUCT.md。

工作原理

网关根据 model 将每个请求路由到已配置的服务提供商， 检查适用的预算，转发调用，并为每个请求写入一条收据，包括被预算拒绝的请求。报告、仪表板和 MCP 工具都会读取这些 收据。详情：docs/ARCHITECTURE.md。

MCP

inferrail mcp 是一个通过 stdio 运行的 MCP 服务，提供两个用于读取 本地收据的只读工具：get_spend（按服务提供商、 模型、路由或任意标签（如 work_id）分组的已知成本和令牌）和 get_health。它们不会 运行推理或写入文件。

claude mcp add inferrail \
  -e INFERRAIL_RECEIPTS_PATH=/absolute/path/to/inferrail-receipts.jsonl \
  -- uvx --with "mcp>=2.0" inferrail mcp

其他客户端，以及 --app-mode 会将收据保存到何处： docs/integrations.md。

当前支持情况

• 端点：POST /v1/chat/completions（兼容 OpenAI）和 POST /v1/messages（兼容 Anthropic），支持流式传输和工具调用；此外还提供 GET /v1/models，供需要先列出模型的客户端使用。任何允许设置基础 URL 并发送这些请求格式的客户端都可以使用。
• **提供商：**OpenAI、Anthropic，以及与其中任一方兼容的端点。内置价格涵盖 OpenAI 和 Anthropic 模型。其他端点 需要在配置中声明价格，否则其费用将保持未知。
• 聊天消息中的图像（image_url 部分，例如浏览器 Agent 的 截图）会转发给兼容 OpenAI 的提供商。在预算中，每张图像会预留固定的 3,000 个 Token 估算额度；实际 费用以提供商报告的用量为准。
• **不支持：**OpenAI Responses API、嵌入、图像 生成、音频和 Realtime API、批处理，以及 Gemini 或 Bedrock 原生 API。网关无法核算的请求 字段会被明确报错拒绝， 绝不会静默丢弃。
• **范围：**只统计通过运行中的网关发出的调用， 不统计你提供商账户上的所有调用。

准确的支持范围和非目标：docs/PRODUCT.md。

**要在生产环境中运行吗？**如果你的产品会运行需要在模型调用上花费 实际资金的 Agent 作业，我可以协助你在自己的工作负载上配置 Inferrail，并确保它持续正常运行。 提交生产环境配置申请 并说明你的作业是什么样的。

文档

• 为单次 AI Agent 运行设置美元预算
• 集成：SDK、框架、归因、MCP、语音
• 自行托管：安装、配置、存储、预算、仪表板
• 产品范围和架构
• openapi.json、config.schema.json、llms.txt

贡献、安全与许可证

问题和 Bug：GitHub issues。 安全或隐私漏洞：请按SECURITY.md中的说明私下报告。贡献：CONTRIBUTING.md （pytest 无需 API 密钥或网络）。许可证：Apache-2.0。