用 Helicone 给 AI Agent 套一层成本与延迟可观测：零代码侵入的轻量代理实操

Helicone 提供云端托管（开箱即用）与自托管（数据完全在自己手里）两种形态。新手建议先用云端：

1. 浏览器打开：helicone.ai
2. 用 GitHub 或邮箱注册登录
3. 进入 Dashboard，点「New Project」创建一个项目
4. 在项目设置里找到「API Keys」，创建一个 Key
   （形如 pk-lf-xxxxxxxxxxxxxxxx，这是你的代理凭证）

拿到后，把它放进环境变量，别写死在源码里。

Helicone 兼容 OpenAI 的接口形态，所以你几乎不用改调用逻辑，只把 base_url 指向 Helicone 网关，并通过请求头带上 Helicone Key。下面是环境变量写法：

# .env 文件（切勿提交到公开仓库）
OPENAI_API_KEY=sk-你的官方模型Key
HELICONE_API_KEY=pk-lf-你的HeliconeKey

# 把官方地址换成 Helicone 网关地址
OPENAI_BASE_URL=https://oai.hconeai.com/v1

对 Anthropic 官方 SDK 同理，把 base_url 换成 https://anthropic.hconeai.com。只要你的代码本来就用一个可配置的 base_url 变量，这一行就是全部改动。

用你熟悉的 SDK 发一次请求，把 base_url 指到 Helicone 网关，并在请求头注入 Helicone Key：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ["OPENAI_BASE_URL"],  # https://oai.hconeai.com/v1
    default_headers={"Helicone-Auth": "Bearer " + os.environ["HELICONE_API_KEY"]},
)

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "用一句话解释什么是智能体。"}],
)
print(resp.choices[0].message.content)

运行后回到 Helicone Dashboard 的「Requests」页面，应该能看到这一条调用——模型、Tokens、耗时、状态都列出来了。看不到的话，先检查 base_url 拼写和 Helicone-Auth 请求头有没有带上。

光看总账还不够，你要知道「客服 Agent 比写作 Agent 贵多少」「哪个用户把额度烧光了」。Helicone 用自定义属性（property）给每次调用贴标签，仪表盘就能按标签聚合：

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ["OPENAI_BASE_URL"],
    default_headers={
        "Helicone-Auth": "Bearer " + os.environ["HELICONE_API_KEY"],
        # 自定义属性：功能模块 + 用户标识 + 请求类型
        "Helicone-Property-Feature": "customer-support",
        "Helicone-Property-User": "user_8821",
        "Helicone-Property-Type": "chat",
    },
)

这样在 Dashboard 里就能切到「Feature = customer-support」看这一块的花费曲线，也能按 User 把成本归属到具体账号。多智能体系统里，建议给每个子 Agent 一个独立的 Feature 标签，谁贵谁便宜一目了然。

跑一段时间后，打开 Helicone 的几个核心面板：

# Dashboard 里重点看三块
Requests      # 单条请求明细，可点开看完整 prompt / 响应 / 报错
Cost          # 按时间、模型、property 聚合的花费曲线
Latency       # p50 / p95 延迟，定位慢调用来自哪个路由

• 成本异常：某天曲线陡增，按 Feature 下钻，通常是某个新上线的 Agent 在死循环调用。
• 延迟异常：p95 明显高于 p50，说明少数请求卡在长上下文或工具调用，考虑加缓存或限流。
• 错误率：5xx 集中出现，先看是不是官方服务抖动，再看是不是自己的 prompt 触发了安全拦截。

Helicone 支持「语义缓存」：内容相近的提问直接命中缓存返回，不再调模型，成本立降。开启方式是在请求头打开缓存开关：

default_headers={
    "Helicone-Auth": "Bearer " + os.environ["HELICONE_API_KEY"],
    "Helicone-Cache-Enabled": "true",
}

同时，在 Dashboard 的 Alerts 里设一条规则：当「单用户 1 分钟花费超过阈值」或「错误率超过比例」时发邮件 / Webhook。这样即使半夜跑飞，你也能第一时间收到通知而不是第二天看账单。