Helicone评测使用教程：为LLM请求加上可观测与打分
Helicone 是一个 LLM 可观测性平台，核心用法是让请求经过它的代理，从而自动记录请求耗时、token 消耗和响应内容。
如果你已经能调用 OpenAI 等模型 API，想给每次请求加上业务标签并做简单评测，可以按下面的步骤接入。
先确认代理地址和鉴权方式
Helicone 的接入方式是在原有 API 地址前拼接代理域名。
以 OpenAI 兼容接口为例，把基础地址从官方地址改为 Helicone 代理地址，并在请求头中带上 Helicone 的 API Key。
你需要先在 Helicone 控制台注册账号，创建一个 API Key，并确认当前使用的模型提供方是否支持该代理路径。
如果使用 OpenAI SDK，可以这样设置：
from openai import OpenAI
client = OpenAI(
api_key="你的模型提供方Key",
base_url="https://oai.helicone.ai/v1",
default_headers={
"Helicone-Auth": "Bearer 你的HeliconeKey"
}
)注意 Helicone-Auth 的值需要带 Bearer 前缀，而 api_key 仍然是模型提供方的 Key。
两者不要混用，否则会出现 401 或代理无法识别请求的情况。
给请求加上业务属性
Helicone 的价值不只是记录原始请求，而是让你按业务维度筛选和评测。
可以在请求头中添加 Helicone-Property-* 自定义属性，例如用户 ID、会话 ID、功能模块。
这些属性会出现在面板的请求详情中，后续做反馈和评测时可以作为筛选条件。
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "用一句话解释什么是向量检索"}],
extra_headers={
"Helicone-Property-UserId": "user_1001",
"Helicone-Property-Feature": "qa_bot"
}
)发送一次请求后，进入 Helicone 控制台的 Requests 页面，应该能看到这条记录，并在详情中看到 UserId 和 Feature 属性。
如果没有出现，先检查请求是否真的走了代理地址，以及请求头拼写是否正确。
用反馈和评测器打分
Helicone 支持对单条请求提交反馈。
在请求详情页可以手动提交评分或反馈标签，也可以通过 API 提交。
反馈适合人工抽检，评测器适合批量打分。
评测器通常需要配置评分提示词和模型，对请求的输入输出进行自动判断。
在控制台进入 Evaluators 或 Scores 相关页面，创建一个评测器，选择要评估的请求范围，然后运行。
运行后回到请求列表，查看对应请求是否出现评分结果。
不同账号套餐对评测器数量和运行频率可能有限制，具体以控制台当前展示为准。
常见报错与排查
请求没有出现在 Helicone 面板：最常见原因是 base_url 仍然指向官方地址，或者请求头没有带 Helicone-Auth。
用 curl -v 查看实际请求地址和请求头，确认代理域名和鉴权头都存在。
返回 401 或 403：先区分是模型提供方 Key 错误还是 Helicone Key 错误。
模型 Key 放在 api_key，Helicone Key 放在 Helicone-Auth 头中。
如果使用环境变量，检查变量名是否拼错、是否在启动进程前已导出。
自定义属性不显示：属性头需要以 Helicone-Property- 开头，后面的名称会作为属性键。
部分 SDK 的 extra_headers 写法不同，确认版本支持该参数；
不支持时可以用 default_headers 或在 HTTP 客户端层统一添加。
评测器运行后没有分数：检查评测器是否绑定了正确的请求筛选条件，以及请求是否包含模型可读取的输入输出内容。
如果请求体被截断或内容为空，评测器可能无法给出有效评分。
验证接入是否完整
完成上述配置后，按三个检查点确认结果：第一，在 Requests 页面能看到新请求，且时间、模型、token 数与实际调用一致；
第二，请求详情中能看到你添加的自定义属性；
第三，手动提交一条反馈或运行一次评测器后，对应请求出现评分记录。
三项都通过，说明 Helicone 的监控和评测链路已经可用。
Helicone评测使用教程的重点不是把所有功能一次配全，而是先让请求稳定经过代理并被正确标记，再逐步加入反馈和自动评分。
如果后续要对比不同提示词或模型版本，可以复用同一套属性命名，方便在面板中按条件筛选和查看评分差异。
