在 highlight.io 中追踪 Python AI / LLM 应用：OpenLLMetry 自动埋点与全链路观测实战

可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载本文介绍如何在 highlight.io 全栈可观测平台中为 Python 的 AI / LLM 应用配置分布式追踪通过 OpenLLMetryTraceloop 开源的 LLM 可观测性方案自动插桩 OpenAI、LangChain、LlamaIndex、Anthropic 等主流 AI 库覆盖模型训练、推理与评估的完整调用链。读者将掌握从安装highlight-io、初始化 SDK、编写可追踪的推理函数到在 highlight.io 追踪门户中验证 LLM 调用耗时与 token 消耗的完整实战路径。一、为什么 Python AI / LLM 应用需要追踪大模型应用与传统 Web 应用的最大差异在于一次用户请求背后往往串联多个外部 AI 服务调用LLM 推理、向量检索、Embedding 生成等这些调用跨越不同供应商、耗时波动大、费用与 token 消耗直接挂钩。highlight.io 通过为 Python SDK 集成 OpenLLMetry把这些第三方库的调用自动转换成 OpenTelemetry 风格的 span让开发者无需在业务代码中手工埋点即可看到一次“提问 → 模型推理 → 返回答案”请求的完整链路、每一环耗时以及 token 统计。该能力覆盖三个典型场景模型推理OpenAI Chat Completion、Anthropic Claude 等推理调用自动成为 span模型训练/评估LangChain、LlamaIndex 的链路与评估流程同样被自动追踪AI 生态周边向量数据库Pinecone、Qdrant、Weaviate、ChromaDB与云厂商服务AWS Bedrock、GCP VertexAI、IBM WatsonX的调用均可纳入同一链路。二、支持的 Python AI / LLM 库一览highlight.io 对 AI / LLM 的追踪基于 OpenLLMetry 实现支持的 Python 库清单在文档 QuickStart 内容中定义见 python-ai.tsx类别库PyPI 包名LLM 提供方Anthropicanthropic、OpenAI / Azure OpenAIopenai、Coherecohere、Replicatereplicate、Hugging Face Transformerstransformers编排框架Langchainlangchain、LlamaIndexllamaindex、Haystackhaystack-ai向量数据库Pineconepinecone、Qdrantqdrant、Weaviateweaviate、ChromaDBchromadb云厂商 AI 服务AWS Bedrockboto3、GCP VertexAIvertexai、IBM WatsonXwatsonx安装你需要的库即可例如pip install openai这一行背后的自动插桩逻辑可以在 Python SDK 源码中直接看到highlight_io/integrations/all.py汇总了 Langchain、LlamaIndex、OpenAI、VertexAI 等所有 AI 集成例如 langchain.py 通过LangchainInstrumentor、llamaindex.py 通过LlamaIndexInstrumentor对库进行自动插桩——也就是说初始化 SDK 后这些集成会被自动加载无需手工开启。三、安装 highlight-io Python SDK在安装 AI 库的同时还需要安装 highlight.io 的 Python SDK# 使用 poetry推荐 poetry add highlight-io # 或使用 pip pip install highlight-io如果你通过 zip 包或 S3 文件上传发布函数如 AWS Lambda请务必确认highlight-io已被打入构建产物否则运行时无法完成自动插桩。四、初始化 Highlight SDK安装完成后在代码中创建highlight_io.H实例。以 OpenAI 为例完整初始化代码定义于 shared-snippets-monitoring.tsx 中的init片段import highlight_io # instrument_loggingTrue 会同时开启日志埋点。 # 如果不想上报日志或正在使用 loguru请传入 instrument_loggingFalse H highlight_io.H( YOUR_PROJECT_ID, instrument_loggingTrue, service_namemy-app, service_versiongit-sha, environmentproduction, )参数说明YOUR_PROJECT_ID替换为你在 highlight.io 创建项目后获得的真实项目 IDinstrument_loggingTrue同时开启 Python 内置 logging 的自动采集见 overview.md 中的日志配置指引service_name/service_version/environment用于在追踪门户中区分服务、定位版本与部署环境建议分别填入应用名、Git SHA 与环境名。SDK 初始化后上文列出的受支持 AI 库会被自动插桩随后所有相关调用都会自动生成 span。五、编写并追踪一个 AI 推理函数初始化完成后只需用highlight_io.trace装饰业务函数即可把一次完整的“提问 → 模型推理 → 返回答案”纳入追踪。官方 QuickStart 的完整示例见 python-ai.tsxfrom openai import OpenAI import highlight_io from highlight_io.integrations.flask import FlaskIntegration H highlight_io.H( YOUR_PROJECT_ID, instrument_loggingTrue, service_namemy-app, service_versiongit-sha, environmentproduction, ) client OpenAI() chat_history [ {role: system, content: You are a helpful assistant.}, ] highlight_io.trace def complete(message: str) - str: chat_history.append({role: user, content: message}) completion client.chat.completions.create( modelgpt-4-turbo, messageschat_history, ) chat_history.append( {role: assistant, content: completion.choices[0].message.content} ) return completion.choices[0].message.content def main(): print(complete(What is the capital of the United States?)) if __name__ __main__: main() H.flush()要点拆解highlight_io.trace为函数创建顶层 span函数内对 OpenAI 的chat.completions.create调用会由自动插桩生成子 span形成complete→openai.chat的父子层级HTTP 触发若在 Flask/FastAPI 等 Web 框架中部署可把complete挂到带 HTTP 触发的 endpoint 或函数上再行验证示例中已导入FlaskIntegration对应实现见 flask.pyH.flush()在脚本式非长期运行服务场景下于主流程结束时显式刷新缓冲确保 span 及时上报上下文保持chat_history在函数内按顺序累积OpenAI 返回的completion.choices[0].message.content既是函数返回值也是追踪结果中可见的 LLM 响应内容。六、在追踪门户中验证与排查运行上述脚本后打开 highlight.io 的 traces 门户确认后端追踪数据持续流入。若未看到数据按以下顺序排查确认highlight-io已安装且被包含在构建产物中Lambda/zip 部署场景确认highlight_io.H使用正确的项目 ID 且已先于 AI 库调用前初始化确认所用 AI 库在受支持清单内见第二节表格脚本场景确认主流程末尾调用了H.flush()。上图是追踪门户中的实际效果截图来自仓库 python-ai-traces.pngWaterfall 面板中可见根 spancomplete (openai-a...)与子 spanopenai.chat (openai-a...)耗时均为 1.435 秒展开子 span 后可以看到完整 LLM 交互元数据——模型gpt-4-turbo、系统/用户提示词、助手回复The capital of the United States is Washington, D.C.、finish_reasonstop以及 token 统计prompt_tokens26、completion_tokens12服务信息service_nameopenai-app、版本1.0.0、环境e2e-test也一目了然。七、与全栈可观测的衔接Python AI / LLM 追踪是 highlight.io 全栈可观测能力的一部分可与其余能力组合使用前端衔接如需将后端 AI 调用与浏览器端会话关联可参考 frontend-backend-mapping.md 配置前端 SDK 的tracingOrigins让一条链路贯通“用户点击 → 前端请求 → 后端 LLM 调用”错误与日志开启instrument_loggingTrue后Python 内置 logging 自动上报结合 python-libraries.tsx 可追踪更多通用 Python 库OpenTelemetry 原生接入若使用自定义框架可参考 python OpenTelemetry 接入 的说明直接上报 OTLP 数据追踪验证参考仓库中还提供了与本文 QuickStart 对应的 traces 版内容 traces/python/python-ai.tsx可用于对照理解同一场景在错误/日志/追踪产品视图下的差异。八、小结在 highlight.io 中启用 Python AI / LLM 追踪只需三步安装highlight-io与所需 AI 库、用highlight_io.H初始化 SDK、用highlight_io.trace包裹业务函数。底层由 OpenLLMetry 自动插桩完成 span 生成开发者无需在每次 LLM 调用处手工埋点即可在追踪门户获得包含调用耗时、提示词/回复内容、token 统计与服务元数据在内的完整推理链路——这对成本核算、性能分析与模型回归排查都具有直接价值。赞分享可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载相关推荐OpenLLMetry终极指南一行代码实现LLM应用全链路追踪OpenLLMetry终极指南一行代码实现LLM应用全链路追踪 想要为你的LLM应用添加完整的可观测性却担心配置复杂、代码侵入性强OpenLLMetry正LLMOps可观测性5个关键步骤用OpenLLMetry实现LLM应用全链路可观测性5个关键步骤用OpenLLMetry实现LLM应用全链路可观测性 在大语言模型应用日益普及的今天如何有效监控和追踪LLM应用的全链路性能成为了开发者的重要挑LLMOps可观测性AG-UI .NET 应用可观测性实战Step14_Telemetry 与 OpenTelemetry 全链路追踪AG UI .NET 应用可观测性实战Step14_Telemetry 与 OpenTelemetry 全链路追踪 本指南围绕 AG UIAgent Use人工智能AI Agent上一篇FileSync故障排除手册解决NAT穿透失败的7个实用技巧下一篇Laravel Developer Roadmap前端基础必备技能清单HTML/CSS/JS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考