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 集成测试目录包含两类测试目标文件作用tests/python_integration_tests.py面向 Helicone 自身网关/代理链路的集成测试直接以 HTTP 请求打到本地 Worker随后查数据库、取对象存储验证请求是否被完整记录tests/e2e_suite.py面向主流 LLM SDKOpenAI、Gemini、Anthropic的端到端测试通过 SDK 客户端把 base_url 指向 Helicone 本地端点验证各类调用形态tests/requirements.txt两个测试文件共用的、版本锁定的 Python 依赖清单tests/test_data/pride.txt用于 Anthropic 缓存cache control测试的长文本语料tests/test_image.png用于多模态vision测试的本地示例图片缺省时相关用例会被 pytest.skip 跳过原文档的核心流程只有三步但每一环背后都有明确的源码实现可供对照下面逐节展开。二、前置准备启动 Helicone Worker原文档第一步要求先进入 worker 目录并执行启动脚本chmod x run_um.sh ./run_um.sh需要说明的是在当前仓库版本中worker 目录下的实际启动脚本是 worker/run_all_workers.sh 与 worker/run_ptb_workers.shREADME 中提及的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_TYPE端口对应线上域名生产路由用途OPENAI_PROXY8787oai.helicone.aiOpenAI 兼容代理端点HELICONE_API8788api.worker.helicone.aiHelicone 记录 APIGATEWAY_API8789gateway.helicone.aiAI 网关/v1/chat/completions等ANTHROPIC_PROXY8790anthropic.helicone.aiAnthropic 兼容代理端点AI_GATEWAY_API8793ai-gateway.helicone.ai新版 AI Gateway API本地开发模式下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 heliconerequests发送代理/网关 HTTP 请求pytest测试运行器与断言psycopg2连接本地 Postgres直接查询request/response表验证记录是否落库python-dotenv配合load_dotenv()从.env文件加载环境变量helicone异步日志测试依赖的官方 Python SDKfrom helicone.openai_async import openai, Meta。如需完全复现仓库锁定的依赖版本建议直接安装 tests/requirements.txtpip install -r requirements.txt该清单包含pytest8.3.4、openai1.59.9、anthropic0.44.0、httpx0.28.1、python-dotenv1.0.1、google-generativeai0.8.4等与两个测试文件 import 一一对应的依赖例如 tests/e2e_suite.py 中导入的openai、google.generativeai、anthropic、PIL、pathlib。在干净环境里建议先用虚拟环境隔离避免与系统 Python 包冲突。四、配置环境变量两个测试文件在模块加载阶段都会调用load_dotenv()从当前目录的.env读取配置缺失必填变量时会在导入阶段直接抛出KeyError。python_integration_tests.py 需要的变量环境变量说明HELICONE_PROXY_URLOpenAI 兼容代理地址本地应为http://localhost:8787ANTHROPIC_PROXY_URLAnthropic 兼容代理地址http://localhost:8790HELICONE_ASYNC_URL异步日志 SDK 的 base URLhttp://localhost:8788HELICONE_GATEWAY_URLAI 网关地址http://localhost:8789OPENAI_API_KEY/ANTHROPIC_API_KEY上游模型供应商密钥由代理转发时使用OPENAI_ORGOpenAI 组织 IDHELICONE_API_KEYHelicone 鉴权密钥请求头Helicone-AuthSUPABASE_KEY/SUPABASE_URLSupabase 访问配置e2e_suite.py 额外需要的变量HELICONE_OAI_BASE_URL、HELICONE_ANTHROPIC_BASE_URL、HELICONE_GATEWAY_BASE_URLGemini 通过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:9000minioadmin/minioadmin、组织 ID 与 Helicone Proxy Key 均为测试固定值。可见运行整套测试前需要先把本地 Postgres 与 MinIO 起好并保证数据表结构可用。五、运行第一套集成测试python_integration_tests.py在tests/目录下执行原文档给出的命令即可pytest python_integration_tests.py该文件共 9 个测试函数覆盖了 Helicone 记录链路的多个关键能力测试函数验证的能力关键标识/请求头test_gateway_apiAI 网关/v1/chat/completions链路Helicone-Target-Urltest_openai_proxyOpenAI 代理普通补全Helicone-Request-Idtest_openai_proxy_streamOpenAI 代理流式补全stream: truetest_helicone_proxy_key代理密钥鉴权Authorization: Bearer sk-helicone-proxy-*test_openai_async异步日志 SDKhelicone 包Meta(custom_properties...)test_prompt_threat提示词安全/威胁检测Helicone-Prompt-Security-Enabled: truetest_gpt_vision_requestGPT-4 Vision 多模态image_url内容块test_claude_vision_requestClaude 多模态base64type: image base64test_dalle_image_generationDALL·E 3 图像生成/images/generations5.1 网关与代理链路test_gateway_api演示了网关模式向helicone_gateway_url/v1/chat/completions发送请求同时带上Helicone-AuthHelicone 鉴权、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 异步日志 SDKtest_openai_async走的是异步记录模式通过 helicone Python SDK 配置helicone_global.api_key与helicone_global.base_url然后用openai.ChatCompletion.create(..., helicone_metaMeta(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发请求后time.sleep(3)——注释明确说明 Helicone needs time to insert request into the database即记录是异步写入的需要等待落库fetch_from_db用 psycopg2 查 Postgres 的request/response表确认按Helicone-Request-Id能找到记录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 的调用串进同一条会话验证跨模型会话归集能力。覆盖矩阵如下Provider用例验证点OpenAItest_openai_instruct/_streamingInstruct 普通与流式补全OpenAItest_openai_chat_completion/_streamingChat 补全与流式helicone-stream-usage: true头OpenAItest_openai_chat_with_imagebase64 本地图片多模态缺test_image.png时自动 skipOpenAItest_openai_function_callingfunction calling断言message.function_callOpenAItest_openai_image_generationDALL·E 3response_formatb64_jsonGeminitest_gemini_completion/_streamingmodels/gemini-1.5-flash生成Geminitest_gemini_with_imagePIL 读取本地图片后直接传图Anthropictest_anthropic_completion/_streamingClaude 补全与流式Anthropictest_anthropic_with_imagebase64 图片消息Anthropictest_anthropic_tool_call/_tool_use/_tool_streaming工具调用、工具使用完整回合、流式工具调用Anthropictest_anthropic_cachesystem prompt 中cache_control: {type: ephemeral}缓存长文语料来自 tests/test_data/pride.txt通用test_generate_basic请求HELICONE_GENERATE_BASE_URL走 generate 接口附带各 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。用例被跳过skippedtest_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.pyWorker 启动脚本worker/run_all_workers.sh、worker/run_ptb_workers.shWorker 配置与本地依赖地址worker/wrangler.toml本地基础设施编排docker/docker-compose.ymlPython 异步日志 SDKsdk/python/async提示词安全模块valhalla/prompt_security按本文顺序依次完成 Worker 启动、依赖安装、环境变量配置后两套测试即可在本地跑通透过它们的断言逻辑你也能顺带掌握 HeliconePostgres 存元数据、对象存储存请求体的落库设计为后续二次开发或自建监控调试打下基础。【免费下载链接】helicone Open source LLM observability platform. One line of code to monitor, evaluate, and experiment. YC W23 项目地址: https://gitcode.com/GitHub_Trending/he/helicone创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考