企业官网建设流程全解析

• 可观测性
• 后端

本文介绍如何在 highlight.io 全栈可观测平台中，为 Python 的 AI / LLM 应用配置分布式追踪：通过 OpenLLMetry（Traceloop 开源的 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）：

安装你需要的库即可，例如：

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_logging=True` 会同时开启日志埋点。 # 如果不想上报日志，或正在使用 `loguru`，请传入 `instrument_logging=False` H = highlight_io.H( "<YOUR_PROJECT_ID>", instrument_logging=True, service_name="my-app", service_version="git-sha", environment="production", )

参数说明：

• <YOUR_PROJECT_ID>：替换为你在 highlight.io 创建项目后获得的真实项目 ID；
• instrument_logging=True：同时开启 Python 内置 logging 的自动采集（见 overview.md 中的日志配置指引）；
• service_name/service_version/environment：用于在追踪门户中区分服务、定位版本与部署环境，建议分别填入应用名、Git SHA 与环境名。

SDK 初始化后，上文列出的受支持 AI 库会被自动插桩，随后所有相关调用都会自动生成 span。

五、编写并追踪一个 AI 推理函数

初始化完成后，只需用@highlight_io.trace装饰业务函数，即可把一次完整的“提问 → 模型推理 → 返回答案”纳入追踪。官方 QuickStart 的完整示例（见 python-ai.tsx）：

from openai import OpenAI import highlight_io from highlight_io.integrations.flask import FlaskIntegration H = highlight_io.H( "<YOUR_PROJECT_ID>", instrument_logging=True, service_name="my-app", service_version="git-sha", environment="production", ) 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( model="gpt-4-turbo", messages=chat_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.py）；
• H.flush()：在脚本式（非长期运行服务）场景下，于主流程结束时显式刷新缓冲，确保 span 及时上报；
• 上下文保持：chat_history在函数内按顺序累积，OpenAI 返回的completion.choices[0].message.content既是函数返回值，也是追踪结果中可见的 LLM 响应内容。

六、在追踪门户中验证与排查

运行上述脚本后，打开 highlight.io 的 traces 门户），确认后端追踪数据持续流入。若未看到数据，按以下顺序排查：

1. 确认highlight-io已安装且被包含在构建产物中（Lambda/zip 部署场景）；
2. 确认highlight_io.H使用正确的项目 ID 且已先于 AI 库调用前初始化；
3. 确认所用 AI 库在受支持清单内（见第二节表格）；
4. 脚本场景确认主流程末尾调用了H.flush()。

上图是追踪门户中的实际效果（截图来自仓库 python-ai-traces.png）：Waterfall 面板中可见根 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_reason=stop，以及 token 统计（prompt_tokens=26、completion_tokens=12），服务信息（service_name=openai-app、版本1.0.0、环境e2e-test）也一目了然。

七、与全栈可观测的衔接

Python AI / LLM 追踪是 highlight.io 全栈可观测能力的一部分，可与其余能力组合使用：

• 前端衔接：如需将后端 AI 调用与浏览器端会话关联，可参考 frontend-backend-mapping.md 配置前端 SDK 的tracingOrigins，让一条链路贯通“用户点击 → 前端请求 → 后端 LLM 调用”；
• 错误与日志：开启instrument_logging=True后，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 统计与服务元数据在内的完整推理链路——这对成本核算、性能分析与模型回归排查都具有直接价值。

• 可观测性
• 后端