在 Python/TypeScript LLM 应用中接入…

为 Python 或 TypeScript LLM 应用接入 Phoenix 的 OpenInference 追踪，并系统化处理 Span、会话、生产环境与注释反馈。

适用场景

解决思路

1. Python 项目先读 references/setup-python.md：安装 arize-phoenix-otel，并配置 endpoint。
2. TypeScript 项目先读 references/setup-typescript.md：安装 @arizeai/phoenix-otel，并配置 endpoint。
3. 执行自动埋点时，Python 读 references/instrumentation-auto-python.md：自动 instrument OpenAI、LangChain 等，并参考其中 OTel GenAI native instrumentation 内容。
4. 执行自动埋点时，TypeScript 读 references/instrumentation-auto-typescript.md：自动 instrument 支持的框架。
5. 创建自定义 Span 时，Python 读 references/instrumentation-manual-python.md：用 decorators 创建 custom spans。
6. 创建自定义 Span 时，TypeScript 读 references/instrumentation-manual-typescript.md：用 wrappers 创建 custom spans。
7. 导入 ATIF agent 轨迹时，Python 读 references/instrumentation-atif-python.md：支持 Claude Code、OpenHands、Codex 等。
8. LLM API 调用埋点读 references/span-llm.md：按属性模式设置 model、tokens、messages、cost。
9. 多步骤 workflows/pipelines 埋点读 references/span-chain.md。
10. 文档检索埋点读 references/span-retriever.md：按属性模式设置 documents、scores。
11. 函数/API 调用埋点读 references/span-tool.md：设置 name、parameters。
12. 多步骤推理 agents 埋点读 references/span-agent.md。
13. 向量生成埋点读 references/span-embedding.md。
14. 文档 re-ranking 埋点读 references/span-reranker.md。
15. 安全检查埋点读 references/span-guardrail.md。
16. LLM 评估埋点读 references/span-evaluator.md。
17. Python 用 references/projects-python.md 将 traces 按 application 分组。
18. TypeScript 用 references/projects-typescript.md 将 traces 按 application 分组。
19. Python 用 references/sessions-python.md 跟踪 conversations。
20. TypeScript 用 references/sessions-typescript.md 跟踪 conversations。
21. Python 用 references/metadata-python.md 添加自定义属性。
22. TypeScript 用 references/metadata-typescript.md 添加自定义属性。
23. Python 生产环境用 references/production-python.md 配置批处理与 PII 掩码。
24. TypeScript 生产环境用 references/production-typescript.md 配置批处理与 PII 掩码。
25. 先读 references/annotations-overview.md 了解反馈概念。
26. Python 用 references/annotations-python.md 向 spans 添加反馈。
27. TypeScript 用 references/annotations-typescript.md 向 spans 添加反馈。
28. 读 references/fundamentals-overview.md 了解追踪、Span、属性基础。
29. 读 references/fundamentals-required-attributes.md 查看每种 Span 类型的必填字段。
30. 读 references/fundamentals-universal-attributes.md 查看常见属性，如 user.id、session.id。
31. 读 references/fundamentals-flattening.md 查看 JSON 扁平化规则。
32. 按快速开始工作流执行：setup-{lang} → instrumentation-auto-{lang} → 检查 Phoenix。
33. 按自定义 Span 工作流执行：setup-{lang} → instrumentation-manual-{lang} → span-{type}。
34. 按会话跟踪工作流执行：使用 sessions-{lang} 处理对话分组模式。
35. 按生产工作流执行：使用 production-{lang} 处理批处理、掩码与部署。
36. 按类别前缀导航：references/setup-* 查安装配置，references/instrumentation-* 查自动和手动追踪，references/span-* 查 Span 类型规格，references/sessions-* 查会话跟踪，references/production-* 查生产部署，references/fundamentals-* 查核心概念。
37. 按语言导航：references/*-python.md 查 Python 实现，references/*-typescript.md 查 TypeScript 实现。
38. 按阅读顺序执行：先读 setup-{lang} 对应语言；然后选择 instrumentation-auto-{lang} 或 instrumentation-manual-{lang}；再按需查阅 span-{type}；最后查 fundamentals-* 获取属性规格。
39. 需要外部资料时查阅 Phoenix 文档、OpenInference 规范、Python OTEL 包的 arize-phoenix-otel API、Python 客户端包的 arize-phoenix-client API、TypeScript 包的 @arizeai/phoenix-otel、@arizeai/phoenix-client 等包。

适用边界 · 注意事项

• 未部署或无权访问 Phoenix server 时不适用；该技能要求 Phoenix server。
• 不想引入 arize-phoenix-otel 或 @arizeai/phoenix-otel 依赖时不适用。
• 只需通用 OpenTelemetry 且不需要 OpenInference/Phoenix 的 Span 类型、属性规范或反馈功能时，不建议使用。