企业官网建设流程全解析

Helicone @helicone/async SDK 实战：绕过代理直连的 LLM 可观测性与 OpenLLMetry 集成

【免费下载链接】helicone🧊 Open source LLM observability platform. One line of code to monitor, evaluate, and experiment. YC W23 🍓项目地址: https://gitcode.com/GitHub_Trending/he/helicone

本篇技术指南围绕 Helicone 开源项目中的 sdk/typescript/async/README.md 展开，讲解 Node.js 侧绕过 Helicone Proxy、直接上报 LLM 调用追踪的@helicone/async包：从安装、环境变量配置、HeliconeAsyncOpenAI一行替换接入 OpenAI，到heliconeMeta元信息、自定义属性、错误处理与底层 OpenLLMetry/OpenTelemetry 实现。读完本文，你将掌握在不引入代理网关的前提下，把 OpenAI、Anthropic、Cohere、Bedrock、Google AI Platform、Together 以及 LangChain 的调用统一纳入 Helicone 观测平台的具体方案，并理解其与代理模式的能力边界。

一、什么是 @helicone/async：绕过代理的直连日志方案

Helicone 提供了两种主流接入方式：代理（Proxy）模式与异步直连（Async Logging）模式。@helicone/async属于后者——它不是一个拦截流量的网关，而是一个"包装器"：在应用进程内捕获 LLM 请求与响应，直接通过 HTTP 上报给 Helicone 服务端，全程不需要部署或指向代理服务器。

README 对其定位的描述是：

A Node.js wrapper for logging LLM traces directly to Helicone, bypassing the proxy, with OpenLLMetry.

即：借助 OpenLLMetry 实现标准化的 LLM 遥测（telemetry），将追踪数据直接写入 Helicone。官方文档在 proxy-vs-async 对比页 中对两种模式有完整说明，简单来说：代理模式适合希望获得缓存、限流、重试等网关能力的场景；异步模式则更轻量，适用于无法或不希望走代理的生产架构。

README 列出的核心特性包括：

• 无需代理服务器，直接向 Helicone 上报日志；
• 基于 OpenLLMetry 的标准 LLM 遥测格式；
• 支持自定义属性（custom properties）追踪；
• 支持环境变量配置；
• 完整 TypeScript 类型支持。

在仓库中，该包对应目录为 sdk/typescript/async，package.json声明包名为@helicone/async（当前版本 2.0.2），主入口为 dist/index.js，源码入口 index.ts 只做了一件事——重新导出HeliconeAsyncLogger：

export * from "./async_logger/HeliconeAsyncLogger";

这一行导出的背后，是整个异步日志能力的实现核心 HeliconeAsyncLogger.ts，后文会深入拆解。

二、安装与环境准备

2.1 安装稳定版

README 给出的安装命令十分简洁：

npm install @helicone/async

需要注意的是，README 中的示例代码以require("helicone")方式引入HeliconeAsyncOpenAI。根据官方集成文档 docs/getting-started/integration-method/openai.mdx 的记载，OpenAI 异步包装器的完整安装方式为：

npm install @helicone/helicone@2.1.19

随后以require("helicone")引入即可。也就是说：helicone包负责提供面向 OpenAI 的HeliconeAsyncOpenAI高层封装，而本仓库中的@helicone/async提供底层HeliconeAsyncLogger。两者配合使用即可覆盖从高层 API 到底层遥测的全部需求。

2.2 获取 API Key 并配置环境变量

先注册 Helicone 账号并在开发者控制台获取 API Key，然后设置两个环境变量：

export HELICONE_API_KEY=<your Helicone API key> export OPENAI_API_KEY=<your OpenAI API key>

其中HELICONE_API_KEY用于向 Helicone 上报日志（Bearer认证），OPENAI_API_KEY是你实际调用大模型的凭证。从 HeliconeAsyncLogger.ts 的构造函数可以看到，日志上报地址会根据 API Key 的前缀自动切换区域：

this.baseUrl = opts.baseUrl ?? (opts.apiKey.startsWith("sk-helicone-eu-") ? "https://eu.api.helicone.ai/v1/trace/log" : "https://api.helicone.ai/v1/trace/log");

即：EU 区域的 Key（sk-helicone-eu-前缀）上报到eu.api.helicone.ai，其余 Key 上报到api.helicone.ai；你也可以通过baseUrl参数显式覆盖默认地址。

三、快速上手：把 OpenAI 客户端替换为 HeliconeAsyncOpenAI

README 给出了最基础的用法：实例化HeliconeAsyncOpenAI，并在heliconeMeta中传入 Helicone API Key，之后所有调用行为与原生 OpenAI 客户端一致：

const { HeliconeAsyncOpenAI } = require("helicone"); const openai = new HeliconeAsyncOpenAI({ apiKey: process.env.OPENAI_API_KEY, heliconeMeta: { apiKey: process.env.HELICONE_API_KEY, }, }); const chatCompletion = await openai.chat.completion.create({ model: "gpt-3.5-turbo", messages: [{ role: "user", content: "Hello world" }], }); console.log(chatCompletion.data.choices[0].message);

对照官方集成文档 openai.mdx 中 Node.js 标签页的接入步骤，核心思想是用 Helicone 的包装类替换原生类：

// 原写法 const { ClientOptions, OpenAI } = require("openai"); // 替换为 const { HeliconeAsyncOpenAI as OpenAI, IHeliconeAsyncClientOptions as ClientOptions, } = require("helicone");

替换完成后，Chat、Completion、Embedding 等调用方式与 OpenAI 官方包完全等价，业务代码几乎零改动即可获得可观测性。这种"一行替换"的接入体验与官网欢迎页代码片段 openai-async.tsx 中展示的三步流程（安装包 → 设置HELICONE_API_KEY→ 替换 import）一致。

四、HeliconeMeta 配置项详解

heliconeMeta是异步日志的元信息入口，README 给出了它的完整接口：

interface HeliconeMeta { apiKey?: string; // Your Helicone API key custom_properties?: Record<string, any>; // Custom properties to track cache?: boolean; // Enable/disable caching retry?: boolean; // Enable/disable retries user_id?: string; // Track requests by user }

各字段含义如下：

4.1 与代理模式的能力边界

值得特别说明的是：官方文档 openai.mdx 在 Node.js 标签页明确提示——异步直连模式会失去代理模式提供的一些附加能力：

Async logging loses some additional features such as cache, rate limits, and retries

也就是说，cache、retry这类字段在异步模式下主要用于配置层面的兼容与预留（README 将其列入接口），而真正的缓存命中、限流、重试等网关级能力是由 Helicone Proxy 在流量路径上实现的；如果这些能力是你的硬性需求，应优先评估代理模式。从源码结构看，HeliconeAsyncLogger.ts 的构造与上报逻辑中也并未实现缓存/限流逻辑，与文档描述互相印证。

4.2 官方文档中的 IHeliconeMeta 扩展

此外，openai.mdx 还记录了异步模式下一组更完整的元信息字段：

interface IHeliconeMeta { apiKey?: string; properties?: { [key: string]: any }; user?: string; baseUrl?: string; onLog?: OnHeliconeLog; onFeedback?: OnHeliconeFeedback; } type OnHeliconeLog = (response: Response) => Promise<void>; type OnHeliconeFeedback = (result: Response) => Promise<void>;

• properties/user：分别对应自定义属性与用户标识（与 README 的custom_properties、user_id语义一致）；
• baseUrl：自定义日志上报地址；
• onLog：每次日志上报成功后的回调，可拿到上报响应的Response对象（常用于提取helicone-id）；
• onFeedback：反馈操作完成后的回调。

五、自定义属性与用户追踪

自定义属性是异步日志最实用的能力之一。README 给出的示例为每个请求附加project与environment两个业务维度，并绑定用户 ID：

const openai = new HeliconeAsyncOpenAI({ apiKey: process.env.OPENAI_API_KEY, heliconeMeta: { apiKey: process.env.HELICONE_API_KEY, custom_properties: { project: "my-project", environment: "production", }, user_id: "user-123", }, });

上报后，在 Helicone 控制台即可按project、environment、user_id等维度过滤请求、统计成本与延迟。这非常适合在 A/B 实验、多租户或灰度发布场景下做精细化观测——无需修改业务代码，只需在实例化时声明属性即可。

5.1 底层：withProperties 关联属性

对于非 OpenAI 客户端的自定义场景，底层 HeliconeAsyncLogger 还暴露了withProperties方法，通过 OpenLLMetry 的关联属性机制把自定义键值对挂到当前 trace 上：

withProperties(properties: Record<string, string>, fn: () => any) { return traceloop.withAssociationProperties(properties, fn); }

用法大致为：

const logger = new HeliconeAsyncLogger({ apiKey: HELICONE_API_KEY, providers: {...} }); logger.init(); const result = logger.withProperties({ project: "my-project" }, async () => { // 这里的 LLM 调用会自动关联 project=my-project return runLlmCall(); });

六、异步调用与错误处理

6.1 Async/Await 完整示例

README 提供了一个完整的异步调用范例，包含 system 提示词、参数控制与返回值处理：

async function generateResponse() { try { const response = await openai.chat.completion.create({ model: "gpt-4", messages: [ { role: "system", content: "You are a helpful assistant." }, { role: "user", content: "What is the capital of France?" }, ], max_tokens: 150, }); return response.data.choices[0].message; } catch (error) { console.error("Error:", error); } }

注意返回值通过response.data.choices[0].message获取，这与原生 OpenAI SDK 的响应结构一致——包装器不会改变大模型的返回契约。

6.2 错误处理模式

异步模式下的错误处理与常规 HTTP 客户端相同，README 给出的模式是区分"带响应体的错误"与"网络/传输层错误"：

try { const completion = await openai.chat.completion.create({ model: "gpt-3.5-turbo", messages: [{ role: "user", content: "Hello" }], }); } catch (error) { if (error.response) { console.error(error.response.status); console.error(error.response.data); } else { console.error(error.message); } }

• 存在error.response：说明服务端返回了非 2xx 状态码，可从response.status与response.data获取详情；
• 不存在error.response：多为网络超时、DNS 解析失败等传输层异常，直接输出error.message。

七、底层实现：HeliconeAsyncLogger 与 OpenLLMetry/OpenTelemetry

HeliconeAsyncOpenAI等高层包装器之所以能够工作，底层依赖 HeliconeAsyncLogger.ts 中实现的HeliconeAsyncLogger类。它是理解整个异步日志机制的关键。

7.1 构造参数 IHeliconeAsyncLoggerOptions

type IHeliconeAsyncLoggerOptions = { apiKey: string; baseUrl?: string; providers: { openAI?: typeof OpenAI; anthropic?: typeof anthropic; cohere?: typeof cohere; bedrock?: typeof bedrock; google_aiplatform?: typeof google_aiplatform; together?: typeof Together; langchain?: { chainsModule?: typeof ChainsModule; agentsModule?: typeof AgentsModule; toolsModule?: typeof ToolsModule; }; }; headers?: Record<string, string>; };

可以看出，该日志器在设计上是多 Provider + 框架级的：

• 直接支持 OpenAI、Anthropic、Cohere、Bedrock、Google AI Platform、Together 六家大模型供应商；
• 对 LangChain 提供chains、agents、tools三个子模块的插桩支持；
• headers可向上报请求附加自定义 HTTP 头。

对应地，package.json 的peerDependencies声明了这些供应商 SDK 的版本要求：openai ^5.12.0、@anthropic-ai/sdk ^0.58.0、cohere-ai ^7.18.0、@aws-sdk/client-bedrock-runtime ^3.862.0、@google-cloud/aiplatform ^5.3.0、together-ai ^0.21.1、langchain ^0.3.30。

7.2 init()：启动 OpenLLMetry 插桩

构造函数只负责保存配置，真正启动遥测的是init()方法：

init() { traceloop.initialize({ apiKey: this.apiKey, baseUrl: this.baseUrl, disableBatch: true, exporter: new OTLPTraceExporter({ url: this.baseUrl, headers: { Authorization: `Bearer ${this.apiKey}`, ...this.headers, }, }), instrumentModules: { openAI: this.openAI ?? undefined, anthropic: this.anthropic ?? undefined, // ... 其余 provider 模块 langchain: { chainsModule: this.chainsModule ?? undefined, agentsModule: this.agentsModule ?? undefined, toolsModule: this.toolsModule ?? undefined, }, }, }); }

关键点：

1. OpenLLMetry 初始化：traceloop.initialize来自依赖 @traceloop/node-server-sdk ^0.14.6，它基于 OpenTelemetry 提供面向 LLM 的标准遥测插桩；
2. OTLP HTTP 导出：使用@opentelemetry/exporter-trace-otlp-http的OTLPTraceExporter，通过url直连 Helicone 的 trace 上报端点，Authorization: Bearer <apiKey>完成鉴权；
3. 禁用批处理：disableBatch: true意味着每条 trace 即时导出，便于实时观测，代价是请求量巨大时会产生更多网络请求；
4. 按需插桩：instrumentModules只会对实际传入的 provider 模块进行插桩，未被使用的供应商不会带来额外开销。

7.3 数据流向小结

从源码可以梳理出异步日志的完整数据链路：

业务代码调用 LLM SDK │ ▼ Helicone 包装客户端（如 HeliconeAsyncOpenAI） │ （携带 heliconeMeta） ▼ OpenLLMetry 插桩（@traceloop/node-server-sdk） │ 生成 OpenTelemetry Trace ▼ OTLPTraceExporter → POST {baseUrl}（api.helicone.ai/v1/trace/log） │ Authorization: Bearer <HELICONE_API_KEY> ▼ Helicone 服务端入库 → 控制台可视化

7.4 相关：helpers 包的手动日志能力

如果你需要记录的不是某个供应商 SDK 调用，而是自定义事件（如工具调用、向量数据库检索、普通数据事件），可以关注同仓库的 sdk/typescript/helpers/manual_logger/HeliconeManualLogger.ts。其中HeliconeManualLogger支持logRequest、logStream、logSingleStream、logSingleRequest等方法，并通过 types.ts 中的HeliconeEventTool、HeliconeEventVectorDB、HeliconeEventData类型表达自定义事件结构。它与@helicone/async是互补关系：后者负责自动化插桩，前者负责手动精确控制。

八、收集用户反馈：onLog 回调与 helicone-id

异步模式下要关联"用户反馈"，必须从日志上报响应（而非 LLM 响应）中提取helicone-id。官方文档 openai.mdx 给出的示例：

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY, heliconeMeta: { apiKey: process.env.HELICONE_API_KEY, onLog: async (response: Response) => { const heliconeId = response.headers.get("helicone-id"); await openai.helicone.logFeedback( heliconeId, HeliconeFeedbackRating.Positive ); }, }, });

流程拆解：

1. 每次 LLM 调用结束后，onLog回调被触发，入参是日志上报请求的Response；
2. 从响应头helicone-id中取出本次日志的唯一 ID；
3. 调用openai.helicone.logFeedback(heliconeId, rating)把用户反馈（如HeliconeFeedbackRating.Positive）与这条 trace 关联起来。

这是异步模式做 RLHF 风格数据收集、人工评估与数据集标注的标准路径。

九、最佳实践清单

综合 README 与源码，以下是异步直连模式下值得遵循的实践建议：

1. 始终把 API Key 放入环境变量：HELICONE_API_KEY、OPENAI_API_KEY等敏感凭证不要硬编码进源码或提交进仓库；
2. 实现完善的错误处理：区分error.response（服务端拒绝）与传输层异常，避免日志上报失败导致主流程中断——从 HeliconeAsyncLogger.ts 可以看到，上报异常被捕获后仅console.error，不会抛出到业务调用方，属于"日志失败不影响业务"的设计；
3. 善用自定义属性：把项目名、环境、版本、实验分组等元数据放入custom_properties，让后续分析与检索拥有更多维度；
4. 为场景设置合理的超时：LLM 调用耗时长，根据业务容忍度设置超时值；
5. 生产环境实现重试逻辑：网络抖动不可避免，重试策略应当考虑指数退避；同时注意异步直连模式本身不提供代理级的重试/缓存/限流能力，需要时自行实现或切换到代理模式；
6. 多供应商场景使用 HeliconeAsyncLogger 统一接入：利用providers参数一次初始化多个供应商，保持遥测口径一致。

十、许可证与进一步阅读

@helicone/async以 Apache-2.0 协议开源（见 sdk/typescript/async/package.json），你可以自由用于商业项目。若想继续深入，建议阅读仓库内以下资料：

• sdk/typescript/async/README.md：本文依据的原始文档；
• sdk/typescript/async/async_logger/HeliconeAsyncLogger.ts：异步日志底层实现；
• docs/getting-started/integration-method/openai.mdx：OpenAI 异步接入的完整官方指南（含 Node.js/Python/Raw 三种方式）；
• docs/references/proxy-vs-async.mdx：代理模式与异步模式的选型对比；
• sdk/typescript/helpers/manual_logger/HeliconeManualLogger.ts：手动日志与自定义事件上报；
• web/components/templates/welcome/steps/codeSnippets/openai-async.tsx：官网欢迎页展示的三步接入片段。

综上，@helicone/async为"不想引入代理"的 Node.js 应用提供了一条极低侵入的 LLM 可观测性路径：上层用HeliconeAsyncOpenAI一行替换完成 OpenAI 接入，底层以 OpenLLMetry + OTLP 实现标准化遥测直传 Helicone。理解它的配置项与实现边界，能帮助你在代理与直连之间做出符合业务形态的选择。

【免费下载链接】helicone🧊 Open source LLM observability platform. One line of code to monitor, evaluate, and experiment. YC W23 🍓项目地址: https://gitcode.com/GitHub_Trending/he/helicone