AI Footprint

快速开始 · 工具 · 示例 · 架构 · 方法论 · 路线图 · 参与贡献

---

AI Footprint 是一个 MCP 服务和 JSON API，用于估算 AI 消耗的水和能源：聊天提示词、一年的使用量，或根据令牌数估算完整 Agent 会话的消耗。它是 PharmaTools.AI AI 水与能源计算器背后的引擎，并以 Agent 可调用的工具形式提供。

公开发表的 AI 单次提示词耗水估算值从 0.3 mL 到 50 mL 不等。造成大部分差异的原因是可以解释的：测量时间、核算边界的划定方式、统计的工作负载类型，以及数据中心所属方。因此，本服务的每个答案都会说明使用的边界、采用的假设和所依据的方法论版本。估算值可以核查，而不只是照搬。

• 确定性。 所有工具都不使用模型。它们依据已发布且有版本记录的方法论进行算术计算：相同输入，相同答案。
• 零配置。 只读托管端点。无需 API 密钥、无需安装、无需账户。
• 与来源保持一致。 测试套件确保服务的输出与计算器页面完全一致。

快速开始

不到 60 秒，即可通过任何 MCP 客户端使用。 添加托管端点：

https://footprint.pharmatools.ai/mcp

Claude Code

claude mcp add --transport http ai-footprint https://footprint.pharmatools.ai/mcp

Claude Desktop 和 claude.ai： 设置 → 连接器 → 添加自定义连接器，然后粘贴 URL。

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "ai-footprint": { "url": "https://footprint.pharmatools.ai/mcp" }
  }
}

其他客户端： 任何支持通过可流式 HTTP 使用远程 MCP 服务的客户端。将其指向上方的 URL。

然后询问：

工作日每天使用 30 次 ChatGPT 提示词，一年下来会消耗多少水？

estimate_ai_footprint(queries_per_day=30, days=250)

→ 2.6 kWh and 10.5 L over 250 days (comprehensive boundary)
  per prompt: 0.34 Wh, 1.39 mL · about 25.5 hrs of TV or 170 phone charges
  methodology 2026-10 · source: pharmatools.ai/water-consumption-calculator

不使用 MCP？ 同样的工具也提供普通 GET 端点：

curl "https://footprint.pharmatools.ai/api/footprint?queries_per_day=30&days=250"

工具

工具	可以询问	返回内容
estimate_ai_footprint	“每天 30 条提示词，持续一年”	每条提示词、每天和总计的能耗与用水量，并附日常事物对比和假设。使用强度可选 simple（约 0.34 Wh）、mixed（约 1 Wh）或 intensive（约 3 Wh）；边界可选 onsite 或 comprehensive。
estimate_session_footprint	“20 万输入、300 万缓存、4 万输出 token”	Agent 或编码会话的中心估值及 0.3–3× 范围，并说明相当于多少条典型聊天提示词。
compare_water_use	“500 mL 算多吗？”	换算为茶匙、瓶装水和淋浴时间，并列出生命周期项目（A4 纸、杏仁、茶、汉堡）；同时说明这些项目的核算边界宽得多。
get_methodology	“为什么估算值差别这么大？”	每条提示词的数值、两种边界、来源、局限性、引用说明，以及已发布估算值相差约 100× 的四个原因。

这四个工具都标注为只读、幂等且封闭世界，因此客户端可以确认调用它们是安全的。更多内容见 examples/：Python MCP 客户端、无需依赖的 JavaScript 客户端、每个端点的 curl 示例，以及完整的响应记录。

架构

flowchart LR
    A["MCP clients<br/>Claude · Cursor · agents"] -->|/mcp| R
    B["Scripts and browsers"] -->|/api/*| R
    C["Calculator page<br/>pharmatools.ai"] -->|/tighten · /read-claim| R

    subgraph app["One ASGI app · server/main.py"]
        R{{"Path router<br/>CORS · rate limits"}}
        R -->|"open CORS · 120/min"| M["MCP tools<br/>FastMCP, streamable HTTP"]
        R -->|"open CORS · 120/min"| J["JSON API<br/>FastAPI GET routes"]
        R -->|"pharmatools.ai only · daily caps"| T["Prompt tightener"]
        M --> F[("footprint.py<br/>constants · sources · arithmetic")]
        J --> F
    end

    T --> H["Claude Haiku"]

• 单一事实来源。 server/footprint.py 保存所有常量、来源和计算逻辑。MCP 工具和 JSON API 都是轻量封装，因此不会出现偏差；测试也会校验它们是否与计算器页面上的数值一致。
• 一个应用，两种安全策略。 足迹路由提供公开的算术运算：开放 CORS，每个客户端每分钟 120 次请求。/tighten 会消耗 API 额度，因此只接受来自计算器页面的请求，并受到每 IP 和全局每日上限的约束。一个小型 ASGI 封装会根据路径选择相应策略。
• 无状态。 没有数据库，也没有会话。MCP 服务以无状态 JSON 响应模式运行，因此任意实例都能响应任意请求。速率限制保存在内存中，因此假设只运行单个实例（见路线图）。
• 默认保护隐私。 日志只记录工具或端点名称，不记录输入、提示词或 IP 地址。

方法论

先估算能耗，再据此推算用水量。

	数值	依据
能耗，简单文本提示词	~0.34 Wh	OpenAI 给出的每次查询数值；Google 报告称，Gemini 文本提示词的能耗中位数为 0.24 Wh（2025 年）
能耗，图像或长篇推理	~3 Wh 或更多	MIT Technology Review 分析（2025 年）
用水量，onsite 边界	~1.0 mL/Wh	仅计算数据中心冷却用水量，据 Google 披露推算。采用已公布的服务提供商数据中最高的数值。
用水量，comprehensive 边界	~4.1 mL/Wh	加上发电消耗的 ~3.1 mL/Wh 用水量（美国电网平均值，Li 等人）
典型文本提示词	~0.34 mL（现场），~1.4 mL（综合）	广为引用的 2023 年估算所描述的硬件已不复存在

会话估算值经过校准，使得在前沿模型上约 1,000 个输入 token + 约 400 个输出 token 等于一个典型提示词（0.34 Wh），其中输出 token 的能耗约为输入 token 的 5 倍，缓存读取约为输入 token 的 0.1 倍。这些是估算假设，并非测量结果，因此工具会返回一个范围，并明确说明这一点。

局限性。 服务提供商的数据未经同行评审，描述的是提示词中位数，且不包括训练。发电用水量采用美国电网平均值。结果仅供参考。

来源。 Google（2025 年） · OpenAI 每次查询数据 · Li 等人，《让 AI 更节水》 · MIT Technology Review（2025 年） · Water Footprint Network

完整说明请见计算器页面。方法论变更时，会递增 METHODOLOGY_VERSION，并在变更日志中记录。发现更好的来源？提交方法论问题。

JSON API

相同的 4 个工具以支持开放 CORS 的 GET 端点提供。GET /api 会列出这些端点。

端点	参数
/api/footprint	queries_per_day（必填）、usage=simple|mixed|intensive、boundary=onsite|comprehensive、days
/api/session	input_tokens、output_tokens（必填）、cached_input_tokens、model_class=small|frontier|reasoning、boundary
/api/compare	water_ml（必填）
/api/methodology	无

输入无效时会返回 400，并说明允许的输入。响应可缓存 1 小时。每个客户端的请求限制为每分钟 120 次。

自托管

git clone https://github.com/nickjlamb/ai-footprint && cd ai-footprint/server
pip install -r requirements.txt
MOCK=1 uvicorn main:app --port 8000
# MCP at http://localhost:8000/mcp · JSON API at http://localhost:8000/api

MOCK=1 会让文本精简工具返回预设改写内容，因此无需 Anthropic 密钥。无论哪种情况，足迹工具都不需要密钥。随附的 Procfile 可直接用于 Railway、Render、Heroku 等平台。

配置

变量	默认值	用途
ANTHROPIC_API_KEY	无	除非设置 MOCK=1，否则 /tighten 必填
MOCK	未设置	1 会返回预设的文本精简工具响应
MODEL	claude-haiku-4-5	文本精简工具使用的模型
ALLOWED_ORIGINS	https://www.pharmatools.ai,https://pharmatools.ai	/tighten 的 CORS 允许列表
PER_IP_PER_MIN / PER_IP_PER_DAY	4 / 25	文本精简工具的客户端请求限制
GLOBAL_PER_DAY	1500	所有客户端共用的文本精简工具每日上限
MAX_INPUT_CHARS	1500	文本精简工具的输入上限
PUBLIC_PER_IP_PER_MIN	120	/mcp 和 /api/* 的请求限制
DOCS_URL	https://www.pharmatools.ai/mcp#footprint	/ 重定向到的地址
PROXY_ENTRIES	1	托管代理在 X-Forwarded-For 右侧添加的条目数（Railway：1）。请求限制会使用这些条目中紧邻它们左侧的条目；更靠左的条目会被忽略

## 本仓库还包含：提示词优化器

POST /tighten 为计算器页面上的“让首次提示词成为唯一提示词”工具提供支持。它会将提示词草稿发送给 Claude Haiku，由模型改写提示词，让它首次就能获得可用的回答，并使用 [placeholders] 填补信息缺口，而不是编造事实。随后，页面会显示这次改写本身消耗的水量，以及它预计能减少的后续提问所消耗的水量。与足迹工具不同，这项功能会调用模型，因此受到严格限制：仅允许来自 pharmatools.ai 的 CORS 请求、输入上限为 1,500 个字符、设有每个 IP 和每日的请求上限、强制使用工具输出，且不记录提示词。页面嵌入代码位于 web/prompt-tightener-embed.html。

POST /read-claim 为同一页面上的标题核查工具提供支持。页面会在浏览器中自行读取常见说法和简单数据。只有在无法自行读取且访客选择使用该功能时，才会将说法发送到这里。模型只提取说法中的内容（数量、单位及其对应对象），页面再根据固定规则进行说明。它采用与 /tighten 相同的保护措施。

开发

cd server
pip install -r requirements.txt -r requirements-dev.txt
MOCK=1 python -m pytest -q      # tests, including parity with the calculator page
ruff check ..                   # lint

CI 会在 Python 3.10 至 3.13 上运行 lint 和测试，随后启动服务，并使用 MCP 客户端示例 进行端到端测试。推送 v* 标签会发布 GitHub 版本，并附上取自变更日志的说明。

server/
  footprint.py        constants, methodology and arithmetic (single source of truth)
  mcp_tools.py        the four MCP tools
  main.py             ASGI app: /mcp, /api/*, /tighten, /read-claim, CORS and rate limits
  test_footprint.py   parity, validation and HTTP tests
examples/             MCP client, JS and curl examples, captured outputs
web/                  calculator-page embed for the tightener
server.json           MCP Registry entry

隐私

托管服务不会记录你提出的问题。日志仅包含所调用工具或端点的名称，不包含其他内容：没有输入、提示词或 IP 地址。客户端 IP 地址仅保存在内存中，用于执行速率限制。它们绝不会被记录或写入磁盘，并会在服务重启时丢弃。服务没有数据库，也不需要账户。服务运行在 Railway 上，不会与他人共享任何信息。完整政策：pharmatools.ai/privacy-policy。有疑问请联系：[email protected]。

参与贡献

欢迎提交问题和拉取请求，尤其欢迎提供更好的资料来源。请先阅读 CONTRIBUTING.md：数值变更需遵循简短的方法流程，确保服务与计算器页面保持同步。安全问题请通过 SECURITY.md 提交，不要发布为公开问题。

在你的网站上嵌入计算器

只需一行代码，无需账户或密钥。任何允许使用 script 标签的网站都能运行，包括 WordPress、Webflow、Squarespace 和 Ghost。

<script src="https://footprint.pharmatools.ai/widget.js" data-theme="auto" data-prompts="25" data-mix="text" async></script>

可选项：data-theme（light、dark、auto）、data-accent（十六进制颜色，例如 0d7377）、data-prompts（1–200）、data-mix（text、mixed、intensive）和 data-basis（comprehensive、onsite）。如果不允许使用脚本，也可以直接使用 iframe：

<iframe src="https://footprint.pharmatools.ai/widget?theme=auto&prompts=25" title="AI water and energy calculator" width="100%" height="560" style="border:0;max-width:640px" loading="lazy"></iframe>

该组件使用与 API 相同的数值和方法版本，在访客的浏览器中完成所有计算，且不会设置 Cookie。计算器页面提供了一个带实时预览的构建器。

引用

Lamb, N. (2026). 一种用于估算 AI 使用水足迹和能源足迹的能源优先方法（方法版本 2026-10）[预印本]。Zenodo。https://doi.org/10.5281/zenodo.23417340

GitHub 的 引用此仓库 按钮会根据 CITATION.cff 提供软件引用信息。

许可证

MIT © PharmaTools.AI