Helicone/helicone · 上手攻略

• 仓库：Helicone/helicone
• 链接：https://github.com/Helicone/helicone
• 分类：ai
• 作者：Tom
• 更新：2026-07-12

这是什么

Helicone 是一个开源的 LLM 可观测性（Observability）与 AI 网关（AI Gateway）平台，定位是帮助 AI 工程师一站式完成模型调用监控、成本分析、流量路由、Prompt 版本管理和微调数据准备。它诞生于 Y Combinator W23 批次，GitHub Stars 已超过 5,900（数据截至 2026-07），是 LLM 运维领域最活跃的开源项目之一。

核心能力分两层： - 可观测性层：记录每一次 LLM API 调用（请求、响应、延迟、成本），支持 OpenAI、Anthropic、Google Gemini、Azure OpenAI、Ollama 等 100+ 提供商 - AI 网关层：通过统一 API 接口做智能路由、自动降级（fallback）和多模型负载均衡

解决什么问题

在生产环境中跑 LLM 应用，最常见的三类痛点是：

1. 看不见：不知道每个模型的实际调用量、延迟分布、失败率；线上出 bug 时缺少 trace 可查
2. 管不住：跨多个 API 提供商（OpenAI、Anthropic、本地 Ollama）的密钥分散，成本无法统一归因
3. 改不了：Prompt 改一行要改代码、重新部署，生产环境的 Prompt 版本管理几乎不存在

Helicone 用一行代码接入，让以上问题全部变成 Dashboard 上点点鼠标的事。

快速安装

云端版本（推荐，快速上手）

1. 在 helicone.ai/signup 注册，拿到 API Key
2. 在代码中改一行 baseURL 和 API Key：

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://ai-gateway.helicone.ai",  // 改这里
  apiKey: process.env.HELICONE_API_KEY,       // 你的 Helicone API Key
});

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",   // 也可以用 claude-sonnet-4、gemini-2.0-flash 等
  messages: [{ role: "user", content: "Hello!" }]
});

Python 同理，将 base_url 指向 https://ai-gateway.helicone.ai 即可。

自托管（Docker）

需要自己运行完整的 Helicone 栈（Web + Worker + Jawn + Supabase + ClickHouse + MinIO）：

git clone https://github.com/Helicone/helicone.git
cd docker
cp .env.example .env
# 编辑 .env 填入必要的配置
./helicone-compose.sh helicone up

企业级用户可联系 enterprise@helicone.ai 获取 Helm Chart。

核心用法

1. 可观测性：查看调用日志

接入后直接打开 helicone.ai/dashboard，能看到：

• 请求日志：每轮对话的模型、token 消耗、延迟、状态码
• Sessions：将多轮对话聚合成一个 Session，方便追踪完整用户旅程
• 成本分析：按模型、按时间段、按 API Key 拆分的成本报表

2. AI 网关：统一调用 100+ 模型

不需要为每个模型单独配置 SDK，通过 Helicone 一个端点访问所有：

// 一个端点，切换模型只需改 model 字段
const response = await client.chat.completions.create({
  model: "claude-sonnet-4-20250514",   // 换模型
  // model: "gemini-2.0-flash",          // 或任一支持的模型
  messages: [{ role: "user", content: "Hello!" }]
});

3. 自动降级（Automatic Fallback）

在 Helicone Dashboard 配置：当主模型响应失败或超时时，自动切换到备用模型，无需改代码。

4. Prompt 版本管理

在平台上手动编辑 Prompt，通过 AI Gateway 部署——代码无需改动，通过版本控制实现生产环境 Prompt 的灰度发布和回滚。

5. 微调数据准备

从实际请求日志中筛选高质量数据，一键导出为微调格式，对接 OpenPipe 或 Autonomi 等微调服务商。

6. 接入 LangChain

# Python / LangChain 接入
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4o-mini",
    base_url="https://ai-gateway.helicone.ai",
    api_key=os.getenv("HELICONE_API_KEY")
)

典型适用场景

坑与注意

1. 免费额度有限：每月 10,000 次请求，超出需付费；个人项目或小团队初期够用，中型生产环境记得关注用量。
2. 自托管有一定复杂度：涉及 5 个微服务（Web/Worker/Jawn/Supabase/ClickHouse），生产级部署建议用 Kubernetes 而非纯 Docker Compose。
3. 日志数据主权：云端版本日志在 Helicone 服务器，自托管版数据完全在自己手中，敏感业务建议自托管。
4. 异步日志（OpenLLMetry） vs 同步网关：两者是不同接入方式，异步日志只负责记录，不做网关路由，按需选择。
5. 部分集成需要 Helicone API Key：不仅是替换 baseURL，部分框架集成需要额外配置。
6. 企业特性需联系销售：SOC 2 / GDPR 合规、SSO、VIP 支持等需要企业套餐。

与同类对比

一句话：Helicone 是目前唯一同时具备「开源可观测性 + AI 网关 + Prompt 管理」三合一能力的平台；LangSmith 功能全但闭源且贵；Phoenix 偏评测而非生产监控；Lunary 更轻量但路由能力弱于 Helicone。

一句话推荐结论

在生产环境跑 LLM 应用的团队，Helicone 是目前最值得先接进来的开源可观测性工具——一行代码接入后立即能看到成本和延迟，生产问题有据可查，AI Gateway 还能省掉自己搭路由层的麻烦。