Distil

一个无服务器提示压缩 MCP 连接器，可快速压缩提示，并返回 Distil 风格指标 —— 令牌、成本、延迟、计算负载、能耗和碳排放 —— 其中每个数字要么是实测值，要么是明确标注的估算值。完整设计见 SPEC.md。

围绕源白皮书的 Prompt Intelligence 以及令牌/成本/计算/能源/碳层构建（可构建的部分 —— 无需 GPU 硬件）。

亮点

• 浏览器扩展： 直接压缩你在 claude.ai、chatgpt.com 和 gemini.google.com 中输入的内容 —— 无需 API 密钥，可在你正常登录的聊天会话中工作。参见 extension/README.md。

• LLM 网关： 面向 OpenAI/Anthropic/Gemini 的即插即用代理 —— 将你的 base_url 指向 Distil，每个请求在到达真实提供商之前都会被压缩（可选治理），包括流式传输。见下文。

• 快速 + 无服务器： 默认启发式压缩是纯 Python（约 3 毫秒，无模型，无 API 密钥）。可选 gpt-4o-mini 模式以获得更高质量。

• MCP 连接器： 通过流式 HTTP 暴露 5 个工具 + 一个指标资源。

• Distil 指标： 令牌/成本/延迟（实测）+ 能源/碳/GPU 负载（估算，已标注）。通过计算负载模型保留 GPU 意图，而非伪造。

• 实时仪表盘 + 公共 /metrics 端点。

• 诚实设计： 每个估算都标记为 estimated: true；闭源模型参数标记为 params_known: false。

Related MCP server: token-optimization-mcp

LLM 网关（即插即用代理）—— 商业产品

将你现有的 OpenAI/Anthropic/Gemini 客户端指向 Distil，而不是直接指向提供商。Distil 压缩提示，使用你自己的 API 密钥将其转发给真实提供商，并将答案直接流式返回 —— 请求/响应形状相同，因此你的代码除了 base URL 之外无需更改。

your app → Distil (/v1/...)  →  compress + optional governance  →  real provider  →  same answer back to you

一行更改（OpenAI SDK）：

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_OWN_OPENAI_KEY",       # unchanged — sent straight through, never stored
    base_url="https://getdistil.vercel.app/v1",
)
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Could you please possibly explain, in a very detailed way, what a REST API is?"}],
)

curl（证明压缩 + 正常答案 + 节省头）：

curl -i https://getdistil.vercel.app/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Could you please possibly explain, in a very detailed way, what a REST API is?"}]
  }'
# Response body is a normal OpenAI chat.completion object.
# Response headers include:
#   x-distil-original-tokens, x-distil-sent-tokens, x-distil-tokens-saved

Anthropic 和 Gemini 的工作方式相同 —— 只有 base URL/路径和认证头不同（你现有的客户端库会处理这些）：

行为

• 你的密钥，你的账单。 Distil 将你在每个请求中发送的 Authorization/x-api-key/key 直接转发给真实提供商。Distil 从不存储它 —— 只在内存中保留一个单向哈希，仅用作速率限制/计量身份。

• 默认压缩内容： 每个 user 角色消息（OpenAI/Anthropic）或 user 角色 contents 条目（Gemini）的文本 —— 涵盖“最新消息”以及粘贴到其中的任何大型上下文/文档。system/system_instruction 和之前的 assistant/model 轮次保持不变。函数/工具模式（tools、tool_calls、tool_result 块）永远不会被触及。

• 故障安全： 如果压缩或治理因任何原因抛出异常，Distil 会转发你原始的未压缩请求，而不是破坏调用。

• 流式传输： "stream": true 会预先压缩一次，然后提供商的 SSE 响应会逐块无缓冲地中继回来（已针对慢速测试源进行本地验证 —— 块按提供商自己的节奏到达，而非批量）。

• 治理模式 通过 x-distil-govern：off（默认 log）从不阻止；log 运行分类/PII/注入/审核检查并记录违规，但仍转发请求；enforce 在判定为 block 时返回提供商形状的 4xx 错误，而不是转发。

配置头（全部可选）

诚实性说明

• 网关中的压缩仅为启发式（没有每次请求的 LLM 调用来压缩 —— 那会使你的延迟和成本翻倍）。它可能读起来略显生硬；如果答案质量在你的提示上下降，请调高 x-distil-ratio（例如 0.7），并在生产环境中依赖它之前进行测试。

• 已针对实时提供商 API 验证，而非猜测：OpenAI 和 Anthropic 的请求/响应/错误/SSE 形状已通过向 api.openai.com 和 api.anthropic.com 发送真实请求（使用无效密钥，以观察真实错误信封）并逐字节检查响应字节来确认。Gemini 的 generateContent 请求/响应/错误形状也以相同方式验证；其流式框架（:streamGenerateContent?alt=sse）是 Google REST 示例中记录的 SSE 模式，但未针对有效的 Gemini 密钥进行实时验证 —— 在依赖它之前请测试此路径。

• 提供商自身响应体中的 usage/令牌计数字段是提供商真实、权威的数字（Distil 不触碰它们）。x-distil-* 头是 Distil 自己对它压缩内容的计数。

快速开始（本地）

pip install -r requirements.txt
python demo.py                    # try the core on a sample
python eval/run_eval.py           # measured eval over sample prompts
pytest tests/                     # test suite
python mcp_server.py              # run the MCP server over stdio
uvicorn api.index:app --port 8000 # run the HTTP server + dashboard
# → open http://localhost:8000/  (dashboard) and /mcp (connector)

MCP 工具

资源：metrics://summary。

每个 compress_prompt 结果还携带分布式追踪跨度（§2.2）—— 测量的子步骤耗时（route、cache_lookup、compress、token_metrics、 estimates）。

语义缓存（§8.2）与多模型路由（§8.4）

• 缓存 —— 两层、无服务器友好：精确（规范化哈希）+ 相似度 （词法余弦，DISTIL_CACHE_THRESHOLD，默认 0.92），因此近乎相同的提示词 可复用先前的压缩结果。按（ratio、quality、model）命名空间隔离。每个 热实例独立。命中率显示在仪表板上。

• 路由 —— route_prompt / target_model="auto" 对提示词复杂度评分 （推理动词、代码、结构、长度），并选择小型或大型模型， 附带每个模型的成本估算，使选择透明可见。

治理工作流

除了 govern 的允许/警告/阻止判定之外，Distil 还支持：

• 模型策略 —— DISTIL_MODEL_POLICY_MODE（默认 denylist | allowlist）

  • DISTIL_DENIED_MODELS / DISTIL_ALLOWED_MODELS。在网关 （请求体中的 model → 403 model_not_allowed）和 process_prompt 中检查。

• 脱敏 / 隔离 / 需审批 —— process_prompt(..., enforcement=) 为 "block"（默认）、"redact"（掩码 PII/机密并继续）、 "quarantine"（暂存以供安全审查）或 "approval"（暂存等待 签署）。隔离/审批立即返回一个审查 ID——在 resolve_review 批准或拒绝之前 不会压缩任何内容。实时 LLM 网关仅支持 block/redact（x-distil-enforcement 头）—— 同步代理调用无法暂停等待人工处理，因此隔离/ 审批仅限 /process 和 MCP。

• 例外工作流 —— grant_exception(scope, value, tenant?, ttl_hours?, reason?) 授予对包或模型阻止的窄范围、限时覆盖，而不是 禁用整个策略。由 check_packages / check_model_policy 自动检查。

• 许可证扫描 —— scan_licenses(text) 对引用的包进行分类 （permissive / weak_copyleft / copyleft / unknown），依据小型离线 注册表；copyleft 命中会将治理升级为 warn（法律审查 标志，而非硬阻止）。未知包会被标记，而非猜测。

• 审计追踪 —— 每次 govern 调用（包括允许）都会写入一条 证据级条目——决策 ID、租户、判定、原因、提示词哈希

  • 60 字符预览（绝不包含完整提示词内容）——与 违规日志分开，因此审计量不会污染 /metrics。 export_audit_log(fmt="csv") 用于交给审计人员。

• 告警 —— DISTIL_ALERT_WEBHOOK_URL（+ DISTIL_ALERT_MIN_SEVERITY， 默认 high）在治理阻止或隔离/ 审批提交时触发 webhook。双形态负载：一个 Slack 兼容的 text 字段 加上一个结构化的 distil_event，用于 PagerDuty/Jira 自动化或 通用工单摄取。故障安全——损坏的 webhook 绝不会影响 触发它的请求。

• 跨提供商路由 —— route_provider_prompt(text)（相对于 route_prompt 的 仅层级推荐）选择真实的提供商 + 模型：检测到 PII/机密的提示词被限制为 DISTIL_TRUSTED_PROVIDERS（默认 local）（当配置了该变量时）；候选按近期健康度 （core.availability，由真实网关流量提供）然后按成本排序，涵盖每个 配置了密钥的提供商，而不仅仅是 OpenAI 的小型/大型层级。

管理端点（/audit、/review-queue/*、/exceptions/*、/alerts/test） 与 API 其余部分采用相同的门控方式——设置 DISTIL_ADMIN_KEY 以要求 专用的 x-admin-key；Distil 目前没有除此之外的角色分离， 因此没有它时任何有效的 Distil 密钥都可以调用这些端点。

部署（无服务器，Vercel）

1. 推送到 GitHub，导入 Vercel（Python / Fluid Compute——自动检测）。

2. 设置环境变量：CONNECTOR_API_KEY（门控 /mcp）、可选 OPENAI_API_KEY （质量模式）、可选 UPSTASH_REDIS_REST_URL + _TOKEN（持久化 指标；否则使用本地 JSON 文件）。

3. 通过连接器设置添加到 Claude → https://<app>.vercel.app/mcp。

指标仪表板：https://<app>.vercel.app/。

指标参考

布局

core/                 compression + intelligence + estimates + metrics store
core/gateway.py        LLM Gateway request rewriting (no networking; pure logic)
mcp_server.py          FastMCP tools/resource
api/index.py            serverless ASGI entrypoint (MCP + dashboard + /metrics + auth)
api/gateway_routes.py   LLM Gateway HTTP routes (/v1/chat/completions, /v1/messages, /v1beta/...)
dashboard/             static metrics page
eval/                  measured evaluation
tests/                 unit tests (tests/test_gateway.py covers the gateway)

从提示词压缩代理复用

tiktoken 计数、填充词列表 + 分析逻辑、指标数据类 模式，以及 OpenAI 接线（用于可选的 LLM 路径）。