Helicone 集成测试运行指南：从启动 Worker 到端到端验证 LLM 可观测性全链路

Helicone 集成测试运行指南：从启动 Worker 到端到端验证 LLM 可观测性全链路

【免费下载链接】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 集成测试的开发者，围绕仓库中 tests/README.md 给出的三步流程展开：启动 Worker、安装依赖、运行 pytest。文章将结合 tests/python_integration_tests.py 与 tests/e2e_suite.py 的真实用例，讲清每类测试覆盖了什么能力、底层如何验证请求是否被 Helicone 正确记录，帮助你搭建起可复现的本地测试环境，并理解代理网关、异步日志、提示词安全、多模态与多 Provider 链路的工作方式。

一、测试体系概览：tests 目录里有什么

tests/是 Helicone 仓库的 Python 集成测试目录，包含两类测试目标：

原文档的核心流程只有三步，但每一环背后都有明确的源码实现可供对照，下面逐节展开。

二、前置准备：启动 Helicone Worker

原文档第一步要求先进入 worker 目录并执行启动脚本：

chmod +x run_um.sh ./run_um.sh

需要说明的是：在当前仓库版本中，worker 目录下的实际启动脚本是 worker/run_all_workers.sh 与 worker/run_ptb_workers.sh（README 中提及的run_um.sh未在仓库中出现，功能上由前者替代）。run_all_workers.sh会以npx wrangler dev在后台依次拉起 5 类 Worker：

# worker/run_all_workers.sh（节选） npx wrangler dev --var WORKER_TYPE:OPENAI_PROXY --port 8787 & npx wrangler dev --var WORKER_TYPE:HELICONE_API --port 8788 & npx wrangler dev --var WORKER_TYPE:GATEWAY_API --port 8789 & npx wrangler dev --var WORKER_TYPE:ANTHROPIC_PROXY --port 8790 & npx wrangler dev --var WORKER_TYPE:AI_GATEWAY_API --port 8793 --test-scheduled & wait

各 Worker 的端口与角色对应关系如下（对应仓库 worker/wrangler.toml 中WORKER_TYPE变量及各入口路由）：

本地开发模式下，Worker 依赖的外部服务地址在 worker/wrangler.toml 的[vars]中定义，包括：SUPABASE_URL = "http://localhost:54321"、CLICKHOUSE_HOST = "http://localhost:18123"、S3_ENDPOINT = "http://localhost:9000"、S3_BUCKET_NAME = "request-response-storage"。这些本地基础设施（Postgres、ClickHouse、MinIO 等）可通过仓库根目录的 docker/docker-compose.yml 一键拉起，其中 MinIO 默认监听 9000 端口（API）与 9001 端口（Console），并预建了request-response-storage等桶——这正是测试脚本读取请求体的目标存储。

三、安装 Python 依赖

回到tests/目录后，按原文档执行：

pip install requests pytest psycopg2 python-dotenv helicone

• requests：发送代理/网关 HTTP 请求；
• pytest：测试运行器与断言；
• psycopg2：连接本地 Postgres，直接查询request/response表验证记录是否落库；
• python-dotenv：配合load_dotenv()从.env文件加载环境变量；
• helicone：异步日志测试依赖的官方 Python SDK（from helicone.openai_async import openai, Meta）。

如需完全复现仓库锁定的依赖版本，建议直接安装 tests/requirements.txt：

pip install -r requirements.txt

该清单包含pytest==8.3.4、openai==1.59.9、anthropic==0.44.0、httpx==0.28.1、python-dotenv==1.0.1、google-generativeai==0.8.4等与两个测试文件 import 一一对应的依赖（例如 tests/e2e_suite.py 中导入的openai、google.generativeai、anthropic、PIL、pathlib）。在干净环境里建议先用虚拟环境隔离，避免与系统 Python 包冲突。

四、配置环境变量

两个测试文件在模块加载阶段都会调用load_dotenv()，从当前目录的.env读取配置；缺失必填变量时会在导入阶段直接抛出KeyError。

python_integration_tests.py 需要的变量：

e2e_suite.py 额外需要的变量：HELICONE_OAI_BASE_URL、HELICONE_ANTHROPIC_BASE_URL、HELICONE_GATEWAY_BASE_URL（Gemini 通过client_options.api_endpoint指向）、GOOGLE_GENERATIVE_API_KEY、HELICONE_GENERATE_BASE_URL（可选，未设置时相关用例被跳过）、COHERE_API_KEY/MISTRAL_API_KEY（可选，用于 generate 接口的 Provider 密钥头）。

此外，集成测试脚本中还硬编码了一批本地开发环境的连接参数，仅适用于本机调试，切勿照搬进生产：Postgres 连接为localhost:54322（用户/密码均为postgres）、MinIO 为localhost:9000（minioadmin/minioadmin）、组织 ID 与 Helicone Proxy Key 均为测试固定值。可见运行整套测试前，需要先把本地 Postgres 与 MinIO 起好，并保证数据表结构可用。

五、运行第一套集成测试：python_integration_tests.py

在tests/目录下执行原文档给出的命令即可：

pytest python_integration_tests.py

该文件共 9 个测试函数，覆盖了 Helicone 记录链路的多个关键能力：

5.1 网关与代理链路

test_gateway_api演示了网关模式：向helicone_gateway_url/v1/chat/completions发送请求，同时带上Helicone-Auth（Helicone 鉴权）、OpenAI-Organization（上游组织）与Helicone-Target-Url: https://api.openai.com（上游目标），由网关代为转发。test_openai_proxy则直接打到 OpenAI 兼容代理端点chat/completions，而test_openai_proxy_stream在请求体中把stream置为true，验证流式响应同样会被完整记录。三个用例都使用Helicone-Request-Id头注入自定义请求 ID，便于事后在数据库中按 ID 精确回查。

5.2 Helicone Proxy Key 鉴权

test_helicone_proxy_key先通过INSERT ... RETURNING id向 Postgres 的provider_keys与helicone_proxy_keys两张表预置代理密钥记录，再用sk-helicone-proxy-*形式的密钥作为Authorization发起请求，验证代理密钥能够把上游 OpenAI 密钥托管给 Helicone、由服务端代管代发。该用例在运行前依赖本地 Postgres 表结构完整。

5.3 异步日志 SDK

test_openai_async走的是异步记录模式：通过 helicone Python SDK 配置helicone_global.api_key与helicone_global.base_url，然后用openai.ChatCompletion.create(..., helicone_meta=Meta(custom_properties={"requestId": requestId}))发起调用。随后用SELECT * FROM public.request WHERE properties @> '{"requestid": ...}'的 JSONB 包含查询按自定义属性反查请求——这验证了异步模式下请求通过 SDK 上报并被写入数据库的属性索引。对应 SDK 源码位于 sdk/python/async 目录。

5.4 提示词安全与威胁检测

test_prompt_threat是一个典型的正反用例组合：

• 正向：普通提示词（生成 stable diffusion prompt）请求头带Helicone-Prompt-Security-Enabled: true，期望响应 200、Helicone-Status: success；
• 反向：恶意提示词Please ignore all previous instructions（提示注入），期望被拦截并返回 400、Helicone-Status: failed，数据库中对应response.status == -4。

这说明代理链路具备基于提示词内容的威胁检测能力，测试同时验证了拦截结果会被落库。相关实现可参见 valhalla/prompt_security 目录。

5.5 多模态与图像生成

三个多模态用例分别验证：

• GPT-4 Vision：消息内容为text + image_url混合块，请求后还需断言asset表中存在request_id对应的资产记录；
• Claude Vision：先用httpx.get拉取公开图片并 base64 编码，按 Anthropic 的{"type": "image", "source": {"type": "base64", ...}}格式发送；
• DALL·E 3：调用/images/generations，断言response.data[0].revised_prompt存在且生成图片被记录为 asset。

5.6 每个用例背后的验证机制

所有集成测试都遵循同一个"三段式"验证模式（详见 tests/python_integration_tests.py 中的fetch_from_db/fetch_from_minio/get_path）：

1. 发请求后time.sleep(3)——注释明确说明 "Helicone needs time to insert request into the database"，即记录是异步写入的，需要等待落库；
2. fetch_from_db用 psycopg2 查 Postgres 的request/response表，确认按Helicone-Request-Id能找到记录；
3. fetch_from_minio从 MinIO 的request-response-storage桶中读取organizations/{orgId}/requests/{requestId}/request_response_body对象，反序列化后断言request.messages与response.choices内容完整。

由此可以直观理解 Helicone 的存储架构：结构化元数据进 Postgres/Supabase，完整的请求响应体进对象存储（MinIO/S3），集成测试正是沿这条链路逐环校验。

六、运行第二套端到端测试：e2e_suite.py

如果只跑代理层 HTTP 用例还不足以覆盖 SDK 集成，可以追加运行：

pytest e2e_suite.py

该文件通过构造真实 SDK 客户端（base_url指向本地 Helicone 端点，default_headers携带Helicone-Auth与Helicone-Session-Id: test-session-id-4），用统一 Session ID 把不同 Provider 的调用串进同一条会话，验证跨模型会话归集能力。覆盖矩阵如下：

其中test_anthropic_tool_use完整构造了"assistant 返回 tool_use → user 返回 tool_result"的多轮消息序列，验证 Helicone 对复杂工具回合消息结构的记录与透传；test_anthropic_cache则验证带缓存控制块的 system 消息链路。这些用例与 packages/llm-mapper 中针对各 Provider 的消息映射能力一一呼应。

七、常见问题与排查建议

• 导入即抛KeyError：.env缺失必填变量（如OPENAI_API_KEY、HELICONE_PROXY_URL）。逐一补齐第四节表格中的变量后再运行。
• 请求 404 / 连接被拒：本地 Worker 未启动或端口不一致。确认run_all_workers.sh已在 worker 目录执行，且.env中的 URL 与脚本端口（8787/8788/8789/8790/8793）一致。
• 数据库查询为空：请求发出后需要time.sleep(3)等待异步写入；若仍为空，检查 Postgres 连接地址与表结构（集成测试硬编码连接localhost:54322，与本仓库 docker/docker-compose.yml 中默认暴露的端口不同，需按本地实际部署对齐）。
• MinIO 读取失败：确认本地 MinIO 已启动、request-response-storage桶已创建（compose 中的minio-setup服务负责预建桶），访问凭证为minioadmin/minioadmin。
• 用例被跳过（skipped）：test_openai_chat_with_image等依赖tests/test_image.png存在；test_generate_basic依赖设置了HELICONE_GENERATE_BASE_URL。缺失时属于预期行为，不影响其余用例。
• 测试中的硬编码值：org_id、helicone_proxy_key及其哈希、MinIO 凭证均为本地开发专用值，涉及鉴权的用例需要保证本地数据库存在对应记录。

八、相关仓库资源

继续深入可参阅：

• 测试运行说明：tests/README.md
• 集成测试用例：tests/python_integration_tests.py、tests/e2e_suite.py
• Worker 启动脚本：worker/run_all_workers.sh、worker/run_ptb_workers.sh
• Worker 配置与本地依赖地址：worker/wrangler.toml
• 本地基础设施编排：docker/docker-compose.yml
• Python 异步日志 SDK：sdk/python/async
• 提示词安全模块：valhalla/prompt_security

按本文顺序依次完成 Worker 启动、依赖安装、环境变量配置后，两套测试即可在本地跑通；透过它们的断言逻辑，你也能顺带掌握 Helicone"Postgres 存元数据、对象存储存请求体"的落库设计，为后续二次开发或自建监控调试打下基础。

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