{ "canonical_name": "Arize-ai/phoenix", "compilation_id": "pack_2f00c89c0af044d98e5b3913ef77d213", "created_at": "2026-05-16T08:21:03.855464+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=skill, recipe, host_instruction, eval, preflight", "recommended_asset_types=skill, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `pip install arize-phoenix` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "pip install arize-phoenix", "sandbox_container_image": "python:3.12-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "llm_execute_isolated_install", "sandbox_validation_id": "sbx_50a5f8de4c9e4fd0ba6a224c25e45de5" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_c98e4724fe2e220c023755fe10acf5d9", "canonical_name": "Arize-ai/phoenix", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/Arize-ai/phoenix", "slug": "phoenix", "source_packet_id": "phit_faf3ff49263743b0b12673054924d40d", "source_validation_id": "dval_18c54a158d1a480fa58695632ed35440" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 local_cli的用户", "github_forks": 873, "github_stars": 9699, "one_liner_en": "AI Observability & Evaluation", "one_liner_zh": "AI Observability & Evaluation", "primary_category": { "category_id": "software-development", "confidence": "medium", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:git, cli" }, "target_user": "使用 local_cli 等宿主 AI 的用户", "title_en": "phoenix", "title_zh": "phoenix 能力包", "visible_tags": [ { "label_en": "Browser Agents", "label_zh": "浏览器 Agent", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-browser-agents", "type": "product_domain" }, { "label_en": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Browser Automation", "label_zh": "浏览器自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-browser-automation", "type": "core_capability" }, { "label_en": "Page Observation and Action Planning", "label_zh": "页面观察与动作规划", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-page-observation-and-action-planning", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_faf3ff49263743b0b12673054924d40d", "page_model": { "artifacts": { "artifact_slug": "phoenix", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "pip install arize-phoenix", "label": "Python / pip · 官方安装入口", "source": "https://github.com/Arize-ai/phoenix#readme", "verified": true } ], "display_tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "页面观察与动作规划", "评测体系" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 local_cli的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "AI Observability & Evaluation" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "local_cli", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "skill, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:564072810 | https://github.com/Arize-ai/phoenix | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.3.0", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_d364a0a28a14428baff5ca692cb00578 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.3.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：arize-phoenix: v15.3.0", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.0", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_ad2696a72e314b52b79d157bf261f7bd | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：arize-phoenix: v15.5.0", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.1", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_b75368026b414d1bbe31d7d3e90b2731 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.1 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：arize-phoenix: v15.5.1", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.6.0", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_49d41c4c92f24db2b382ebd014f9bd14 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.6.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：arize-phoenix: v15.6.0", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.7.0", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_826b7f8e0d2342cabfedab3cabb1a2dc | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.7.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：arize-phoenix: v15.7.0", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.9.0", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_0d47708aa40b4b99b3f132751181cf43 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.9.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：arize-phoenix: v15.9.0", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:564072810 | https://github.com/Arize-ai/phoenix | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:564072810 | https://github.com/Arize-ai/phoenix | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_547816d87273465a88a09397fc2c4ab1 | https://github.com/Arize-ai/phoenix/issues/13241 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[security] setup deepsec", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_153e6ddc8487493e893542da4c348bbe | https://github.com/Arize-ai/phoenix/issues/13275 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：[security] setup deepsec", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.10.0", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_1ce89c62b10a43288f4c6394276bc97c | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.10.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：arize-phoenix: v15.10.0", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.4.0", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_fea401ed7b774dc7885c245774e87cce | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.4.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：arize-phoenix: v15.4.0", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.8.0", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_2ecb08e3e7e04b60ac87fab18439546d | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.8.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：arize-phoenix: v15.8.0", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 17 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。", "title": "踩坑日志" }, "snapshot": { "contributors": 179, "forks": 873, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 9699 }, "source_url": "https://github.com/Arize-ai/phoenix", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "AI Observability & Evaluation", "title": "phoenix 能力包", "trial_prompt": "# phoenix - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 phoenix 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-001：项目介绍与快速开始。围绕“项目介绍与快速开始”模拟一次用户任务，不展示安装或运行结果。\n2. page-002：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n3. page-003：数据库模型与迁移。围绕“数据库模型与迁移”模拟一次用户任务，不展示安装或运行结果。\n4. page-004：Tracing 系统实现。围绕“Tracing 系统实现”模拟一次用户任务，不展示安装或运行结果。\n5. page-005：Evaluation 评估系统。围绕“Evaluation 评估系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-001\n输入：用户提供的“项目介绍与快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-002\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-003\n输入：用户提供的“数据库模型与迁移”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-004\n输入：用户提供的“Tracing 系统实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-005\n输入：用户提供的“Evaluation 评估系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-001：Step 1 必须围绕“项目介绍与快速开始”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-002：Step 2 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-003：Step 3 必须围绕“数据库模型与迁移”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-004：Step 4 必须围绕“Tracing 系统实现”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-005：Step 5 必须围绕“Evaluation 评估系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Arize-ai/phoenix\n- https://github.com/Arize-ai/phoenix#readme\n- .agents/skills/agent-browser/SKILL.md\n- .agents/skills/mintlify/SKILL.md\n- .agents/skills/phoenix-cli/SKILL.md\n- .agents/skills/phoenix-design/SKILL.md\n- .agents/skills/phoenix-docs-gap-audit/SKILL.md\n- .agents/skills/phoenix-evals/SKILL.md\n- .agents/skills/phoenix-evals-new-metric/SKILL.md\n- .agents/skills/phoenix-frontend/SKILL.md\n- .agents/skills/phoenix-github/SKILL.md\n- .agents/skills/phoenix-integration-snippets/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 phoenix 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: GenerativeModelStore: _last_fetch_id can regress and defeat incremental （https://github.com/Arize-ai/phoenix/issues/13241）；github/github_issue: [security] setup deepsec（https://github.com/Arize-ai/phoenix/issues/13275）；github/github_release: arize-phoenix: v15.10.0（https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.10.0）；github/github_release: arize-phoenix: v15.9.0（https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.9.0）；github/github_release: arize-phoenix: v15.8.0（https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.8.0）；github/github_release: arize-phoenix: v15.7.0（https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.7.0）；github/github_release: arize-phoenix: v15.6.0（https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.6.0）；github/github_release: arize-phoenix: v15.5.1（https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.1）；github/github_release: arize-phoenix: v15.5.0（https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.0）；github/github_release: arize-phoenix: v15.4.0（https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.4.0）；github/github_release: arize-phoenix: v15.3.0（https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.3.0）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "GenerativeModelStore: _last_fetch_id can regress and defeat incremental ", "url": "https://github.com/Arize-ai/phoenix/issues/13241" }, { "kind": "github_issue", "source": "github", "title": "[security] setup deepsec", "url": "https://github.com/Arize-ai/phoenix/issues/13275" }, { "kind": "github_release", "source": "github", "title": "arize-phoenix: v15.10.0", "url": "https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.10.0" }, { "kind": "github_release", "source": "github", "title": "arize-phoenix: v15.9.0", "url": "https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.9.0" }, { "kind": "github_release", "source": "github", "title": "arize-phoenix: v15.8.0", "url": "https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.8.0" }, { "kind": "github_release", "source": "github", "title": "arize-phoenix: v15.7.0", "url": "https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.7.0" }, { "kind": "github_release", "source": "github", "title": "arize-phoenix: v15.6.0", "url": "https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.6.0" }, { "kind": "github_release", "source": "github", "title": "arize-phoenix: v15.5.1", "url": "https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.1" }, { "kind": "github_release", "source": "github", "title": "arize-phoenix: v15.5.0", "url": "https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.0" }, { "kind": "github_release", "source": "github", "title": "arize-phoenix: v15.4.0", "url": "https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.4.0" }, { "kind": "github_release", "source": "github", "title": "arize-phoenix: v15.3.0", "url": "https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.3.0" } ], "status": "已收录 11 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "AI Observability & Evaluation", "effort": "安装已验证", "forks": 873, "icon": "code", "name": "phoenix 能力包", "risk": "可发布", "slug": "phoenix", "stars": 9699, "tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "页面观察与动作规划", "评测体系" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/Arize-ai/phoenix 项目说明书\n\n生成时间：2026-05-16 08:19:14 UTC\n\n## 目录\n\n- [项目介绍与快速开始](#page-001)\n- [系统架构设计](#page-002)\n- [数据库模型与迁移](#page-003)\n- [Tracing 系统实现](#page-004)\n- [Evaluation 评估系统](#page-005)\n- [Datasets 与 Experiments 数据管理](#page-006)\n- [Prompt Playground 与管理](#page-007)\n- [前端组件架构](#page-008)\n- [部署配置与容器化](#page-009)\n- [Python SDK 参考](#page-010)\n\n\n\n## 项目介绍与快速开始\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-002), [前端组件架构](#page-008)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [OnboardingSteps.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/OnboardingSteps.tsx)\n- [PythonProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n- [TypeScriptProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/TypeScriptProjectGuide.tsx)\n- [phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n- [phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n- [phoenix-mcp/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-mcp/README.md)\n- [api_reference/README.md](https://github.com/Arize-ai/phoenix/blob/main/api_reference/README.md)\n- [DocsToolDetails.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/DocsToolDetails.tsx)\n
\n\n# 项目介绍与快速开始\n\n## 项目概述\n\nPhoenix 是由 Arize AI 开发的一个开源可观测性平台，专注于 LLM（大型语言模型）应用的评估与追踪。该项目提供了一套完整的工具集，帮助开发者监控、调试和优化 AI 应用。\n\n### 核心功能\n\n| 功能模块 | 说明 |\n|---------|------|\n| **追踪系统** | 记录 LLM 应用的全链路执行过程 |\n| **评估框架** | 提供多维度评估指标和自动化评测能力 |\n| ** Playground** | 交互式调试和测试 LLM 提示词 |\n| **数据集管理** | 管理测试数据集和评估基准 |\n| **MCP 服务器** | 支持 Model Context Protocol 的工具集成 |\n\n### 技术栈\n\nPhoenix 采用前后端分离架构，主要由以下部分组成：\n\n- **后端**：Python（基于 FastAPI/Gradio）\n- **前端**：React + TypeScript\n- **数据收集**：OpenTelemetry\n- **评估库**：TypeScript/JavaScript（`phoenix-evals`）\n\n## 快速开始\n\n### Python 环境快速配置\n\n#### 安装依赖\n\n使用 pip 安装 Phoenix OTEL 包：\n\n```bash\npip install arize-phoenix-otel\n```\n\n资料来源：[PythonProjectGuide.tsx:15]()\n\n#### 环境变量配置\n\nPhoenix 支持通过环境变量自动配置。以下是核心环境变量：\n\n| 变量名 | 说明 | 示例值 |\n|--------|------|--------|\n| `PHOENIX_HOST` | Phoenix 服务器地址 | `http://localhost:6006` |\n| `PHOENIX_API_KEY` | API 认证密钥 | `your-api-key` |\n| `PHOENIX_CLIENT_HEADERS` | 自定义请求头（JSON 格式） | `{\"X-Custom\":\"value\"}` |\n| `PHOENIX_COLLECTOR_ENDPOINT` | OTel 收集器地址 | `http://collector:4317` |\n| `PHOENIX_PORT` | HTTP 端口 | `6006` |\n| `PHOENIX_GRPC_PORT` | gRPC 端口 | `4317` |\n| `PHOENIX_PROJECT` | 默认项目名称 | `my-project` |\n\n资料来源：[phoenix-config/README.md:18-26]()\n\n#### Python 集成代码\n\n将以下代码添加到应用**最开头**位置，确保在所有代码执行前初始化追踪：\n\n```python\nfrom phoenix.otel import register\n\n# 注册追踪配置\ntracer_provider = register(project_name=\"your-project-name\")\n```\n\n资料来源：[PythonProjectGuide.tsx:52-54]()\n\n### TypeScript/JavaScript 环境快速配置\n\n#### 安装依赖\n\n```bash\nnpm install @arizeai/phoenix-otel\n```\n\n#### 快速开始代码\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\n\n// 初始化追踪\nregister({ projectName: \"your-project-name\" });\n```\n\n资料来源：[TypeScriptProjectGuide.tsx:14-18]()\n\n### 使用 Phoenix Evals 进行评估\n\n`phoenix-evals` 是一个独立的 TypeScript 评估库，可用于创建自定义分类器：\n\n```typescript\nimport { createClassifier } from \"@arizeai/phoenix-evals/llm\";\nimport { openai } from \"@ai-sdk/openai\";\n\nconst model = openai(\"gpt-4o-mini\");\n\nconst classifier = createClassifier({\n model,\n promptTemplate: `\n 评估任务：判断答案是否包含虚假信息。\n 参考文本：{reference}\n 待评估答案：{answer}\n `\n});\n```\n\n资料来源：[phoenix-evals/README.md:25-37]()\n\n## 架构概览\n\n### 系统组件架构\n\n```mermaid\ngraph TD\n A[AI 应用] -->|OTel 追踪| B[Phoenix Collector]\n B --> C[Phoenix Server]\n C --> D[前端 UI]\n C --> E[API 接口]\n \n F[评估请求] -->|phoenix-evals| E\n G[MCP 客户端] -->|MCP 协议| E\n \n style A fill:#e1f5fe\n style C fill:#fff3e0\n style D fill:#e8f5e8\n```\n\n### 追踪数据流\n\n```mermaid\nsequenceDiagram\n participant App as AI 应用\n participant OTel as OpenTelemetry\n participant Phoenix as Phoenix Server\n participant UI as 前端界面\n \n App->>OTel: 发送追踪数据\n OTel->>Phoenix: 收集并转发 Span 数据\n Phoenix->>UI: 提供实时可视化\n UI->>App: 展示追踪链路\n```\n\n## 认证与 API 密钥管理\n\n当启用认证功能时，Phoenix 提供两种 API 密钥类型：\n\n| 密钥类型 | 管理位置 | 适用场景 |\n|---------|---------|---------|\n| 个人 API 密钥 | 用户 Profile 页面 | 个人开发测试 |\n| 系统 API 密钥 | 系统 Settings 页面 | 生产环境部署 |\n\n资料来源：[PythonProjectGuide.tsx:40-47]()\n\n### 生成 API 密钥\n\n在项目设置页面中，已认证用户可以通过\"生成 API 密钥\"按钮创建新的密钥：\n\n```tsx\n\n```\n\n密钥生成后会自动填充到环境变量配置中。\n\n## MCP 服务器集成\n\nPhoenix 提供 MCP（Model Context Protocol）服务器支持，可通过以下配置集成：\n\n```json\n{\n \"mcpServers\": {\n \"phoenix\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@arizeai/phoenix-mcp@latest\",\n \"--baseUrl\",\n \"https://my-phoenix.com\",\n \"--apiKey\",\n \"your-api-key\"\n ]\n }\n }\n}\n```\n\n资料来源：[phoenix-mcp/README.md:45-57]()\n\n### MCP 工具覆盖范围\n\n| 类别 | 支持的工具 |\n|------|-----------|\n| **提示词管理** | `list-prompts`, `get-prompt`, `get-latest-prompt`, `upsert-prompt` 等 |\n| **项目管理** | 项目创建、查询、更新操作 |\n\n## 文档与资源\n\n| 资源类型 | 链接 |\n|---------|------|\n| 官方文档 | [Phoenix 文档](https://arize-ai.github.io/phoenix/) |\n| API 参考 | `api_reference/` 目录下的 Sphinx 文档 |\n| 源码仓库 | [GitHub 仓库](https://github.com/Arize-ai/phoenix) |\n\n## 下一步\n\n- 配置你的第一个追踪项目\n- 使用 phoenix-evals 创建自定义评估器\n- 通过 MCP 集成扩展工具能力\n- 探索 Playground 进行提示词调试\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[项目介绍与快速开始](#page-001), [数据库模型与迁移](#page-003)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/phoenix/server/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/__init__.py)\n- [src/phoenix/db/models.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/models.py)\n- [app/src/Routes.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/Routes.tsx)\n- [schemas/openapi.json](https://github.com/Arize-ai/phoenix/blob/main/schemas/openapi.json)\n- [app/schema.graphql](https://github.com/Arize-ai/phoenix/blob/main/app/schema.graphql)\n- [js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n- [js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n- [js/packages/phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n\n
\n\n# 系统架构设计\n\n## 概述\n\nPhoenix 是一个开源的可观测性平台，主要用于 LLM 应用的可观测性和评估。该系统采用前后端分离架构，支持分布式追踪、评估和数据分析功能。架构设计围绕以下几个核心目标展开：\n\n- **可观测性**：提供完整的追踪、日志和指标采集能力\n- **评估能力**：支持基于 LLM 的自动化评估框架\n- **多语言支持**：提供 Python、TypeScript/JavaScript 客户端 SDK\n- **可扩展性**：支持通过 MCP (Model Context Protocol) 进行扩展\n\n## 整体架构\n\nPhoenix 系统采用分层架构设计，包含以下主要层次：\n\n```mermaid\ngraph TD\n subgraph 客户端层\n A[Python SDK
arize-phoenix-otel] \n B[TypeScript SDK
@arizeai/phoenix-otel]\n C[Phoenix Client
SDK]\n end\n \n subgraph 服务层\n D[Phoenix Server
HTTP/gRPC]\n E[Phoenix MCP
Model Context Protocol]\n end\n \n subgraph 数据层\n F[(SQLite/PostgreSQL
数据库)]\n G[(矢量数据库
可选)]\n end\n \n subgraph 前端层\n H[React Web App
TypeScript]\n end\n \n A --> D\n B --> D\n C --> D\n D --> F\n D --> G\n H --> D\n```\n\n### 架构组件说明\n\n| 组件层级 | 技术栈 | 说明 |\n|---------|--------|------|\n| 客户端 SDK | Python, TypeScript | OTEL 标准的追踪采集 |\n| 服务端 | Python (FastAPI) | HTTP REST API + gRPC |\n| 数据存储 | SQLite/PostgreSQL | 关系型数据存储 |\n| 前端应用 | React + TypeScript | 用户界面 |\n| 扩展协议 | MCP | 模型上下文协议扩展 |\n\n资料来源：[js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n## 数据模型架构\n\nPhoenix 的数据模型定义在 `src/phoenix/db/models.py` 中，核心实体包括：\n\n### 核心数据实体\n\n| 实体名称 | 用途 | 关键字段 |\n|---------|------|---------|\n| Project | 项目隔离 | id, name, description |\n| Trace | 追踪会话 | trace_id, project_id, start_time |\n| Span | 追踪跨度 | span_id, trace_id, name, start_time, end_time |\n| Annotation | 评估标注 | span_id, name, score, label |\n| Dataset | 数据集管理 | id, name, version |\n| Experiment | 实验记录 | id, dataset_id, project_id |\n\n资料来源：[src/phoenix/db/models.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/models.py)\n\n### 数据模型关系图\n\n```mermaid\nerDiagram\n PROJECT ||--o{ TRACE : contains\n PROJECT ||--o{ EXPERIMENT : contains\n TRACE ||--o{ SPAN : contains\n SPAN ||--o{ ANNOTATION : has\n DATASET ||--o{ EXPERIMENT : used_in\n SPAN }o--|| DATASET : references\n```\n\n## API 架构\n\nPhoenix 提供两套 API 接口体系：REST API 和 GraphQL API。\n\n### REST API (OpenAPI)\n\nREST API 基于 OpenAPI 规范定义，提供标准的 HTTP 接口：\n\n```mermaid\ngraph LR\n A[Client] -->|HTTPS| B[FastAPI Router]\n B --> C[Service Layer]\n C --> D[(Database)]\n```\n\n#### 主要 API 端点\n\n| 端点类别 | 路径前缀 | 功能 |\n|---------|---------|------|\n| 项目管理 | `/v1/projects` | 创建、查询、更新项目 |\n| 追踪 | `/v1/traces` | 追踪数据写入和查询 |\n| 跨度 | `/v1/spans` | 跨度数据管理 |\n| 评估 | `/v1/evaluations` | 评估结果管理 |\n| 数据集 | `/v1/datasets` | 数据集 CRUD 操作 |\n\n资料来源：[schemas/openapi.json](https://github.com/Arize-ai/phoenix/blob/main/schemas/openapi.json)\n\n### GraphQL API\n\nGraphQL API 定义在 `app/schema.graphql`，提供更灵活的查询能力：\n\n```graphql\ntype Project {\n id: ID!\n name: String!\n traces: [Trace!]!\n experiments: [Experiment!]!\n}\n\ntype Trace {\n id: ID!\n projectId: ID!\n spans: [Span!]!\n startTime: DateTime!\n}\n\ntype Span {\n id: ID!\n traceId: ID!\n name: String!\n attributes: JSON!\n annotations: [Annotation!]!\n}\n```\n\n资料来源：[app/schema.graphql](https://github.com/Arize-ai/phoenix/blob/main/app/schema.graphql)\n\n## 前端路由架构\n\nReact 前端应用的路由定义在 `app/src/Routes.tsx`：\n\n```mermaid\ngraph TD\n subgraph 路由结构\n A[/] --> B[Projects]\n A --> C[/projects/:id]\n C --> D[Traces]\n C --> E[Spans]\n C --> F[Experiments]\n C --> G[Evals]\n A --> H[/datasets]\n A --> I[/prompts]\n A --> J[/settings]\n end\n```\n\n### 前端组件分布\n\n| 路由路径 | 组件 | 功能 |\n|---------|------|------|\n| `/` | Projects | 项目列表展示 |\n| `/projects/:projectId` | ProjectDetail | 项目详情视图 |\n| `/projects/:projectId/traces` | TracesView | 追踪数据浏览 |\n| `/projects/:projectId/experiments` | ExperimentsView | 实验管理 |\n| `/datasets` | DatasetsView | 数据集管理 |\n| `/prompts` | PromptsView | Prompt 版本管理 |\n\n## 客户端 SDK 架构\n\n### Python SDK\n\nPython SDK (`arize-phoenix-otel`) 提供 OpenTelemetry 标准的集成能力：\n\n```mermaid\ngraph LR\n A[User Application] --> B[Phoenix OTEL SDK]\n B --> C[OTEL Collector]\n C --> D[Phoenix Server]\n D --> E[(Database)]\n```\n\n#### 环境变量配置\n\n| 变量名 | 说明 | 示例值 |\n|-------|------|--------|\n| `PHOENIX_HOST` | 服务器地址 | `http://localhost:6006` |\n| `PHOENIX_PORT` | HTTP 端口 | `6006` |\n| `PHOENIX_GRPC_PORT` | gRPC 端口 | `4317` |\n| `PHOENIX_API_KEY` | API 认证密钥 | `...` |\n| `PHOENIX_PROJECT` | 默认项目名 | `my-project` |\n\n资料来源：[js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n### TypeScript SDK\n\nTypeScript SDK 提供 Node.js 和浏览器环境支持：\n\n```typescript\n// 核心配置接口\ninterface PhoenixConfig {\n host: string; // 服务器地址\n apiKey?: string; // 认证密钥\n headers?: Record; // 自定义请求头\n}\n```\n\n资料来源：[js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n\n## 评估框架架构\n\nPhoenix Evals 提供基于 LLM 的自动化评估能力：\n\n```mermaid\ngraph TD\n A[评估器配置] --> B[createClassifier]\n B --> C[Prompt 模板]\n C --> D[LLM Provider]\n D --> E[评估结果]\n E --> F[Annotation]\n```\n\n### 评估器创建流程\n\n| 步骤 | 操作 | 说明 |\n|-----|------|------|\n| 1 | 选择 LLM Provider | OpenAI, Anthropic, Azure OpenAI 等 |\n| 2 | 定义 Prompt 模板 | 包含评估标准和输入格式 |\n| 3 | 调用 createClassifier | 创建分类器实例 |\n| 4 | 执行评估 | 传入待评估数据进行评分 |\n| 5 | 生成标注 | 将结果写入 Span Annotation |\n\n资料来源：[js/packages/phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n\n## MCP 扩展架构\n\nPhoenix MCP (Model Context Protocol) 服务器提供工具化扩展能力：\n\n```mermaid\ngraph TD\n A[MCP Client
Claude Desktop] --> B[Phoenix MCP Server]\n B --> C[Phoenix Client SDK]\n C --> D[Phoenix REST API]\n D --> E[(Database)]\n```\n\n### MCP 工具覆盖\n\n| 功能领域 | 工具名称 | 说明 |\n|---------|---------|------|\n| Prompts | list-prompts, get-prompt, upsert-prompt | Prompt 版本管理 |\n| Projects | list-projects, get-project | 项目操作 |\n| Traces | query-traces, get-trace | 追踪查询 |\n| Datasets | list-datasets, get-dataset | 数据集操作 |\n\n资料来源：[js/packages/phoenix-mcp/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-mcp/README.md)\n\n## 服务器初始化流程\n\nPhoenix 服务器的初始化定义在 `src/phoenix/server/__init__.py`：\n\n```python\n# 核心初始化流程\ndef create_app() -> FastAPI:\n # 1. 配置加载\n # 2. 数据库连接初始化\n # 3. 中间件注册\n # 4. 路由注册\n # 5. WebSocket 支持\n # 6. CORS 配置\n```\n\n### 服务器组件初始化顺序\n\n| 顺序 | 组件 | 职责 |\n|-----|------|------|\n| 1 | 配置管理 | 加载环境变量和配置文件 |\n| 2 | 数据库连接 | 建立 SQLAlchemy 会话 |\n| 3 | 认证中间件 | JWT/API Key 验证 |\n| 4 | API 路由 | 注册 REST 和 GraphQL 端点 |\n| 5 | WebSocket 处理 | 实时推送支持 |\n| 6 | 静态文件服务 | 前端资源托管 |\n\n资料来源：[src/phoenix/server/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/__init__.py)\n\n## 部署架构\n\nPhoenix 支持多种部署模式：\n\n```mermaid\ngraph LR\n subgraph 本地开发\n A[开发机器] --> B[Docker Compose]\n end\n \n subgraph 云端部署\n C[云服务器] --> D[Container/K8s]\n end\n \n subgraph 托管服务\n E[Arize Cloud] --> F[托管 Phoenix]\n end\n```\n\n### 部署配置矩阵\n\n| 部署模式 | 数据库 | 适用场景 | 扩展性 |\n|---------|-------|---------|--------|\n| 本地开发 | SQLite | 个人测试 | 单一实例 |\n| 生产部署 | PostgreSQL | 企业使用 | 水平扩展 |\n| 托管服务 | 云数据库 | 快速启动 | 自动扩展 |\n\n## 安全架构\n\n### 认证机制\n\n| 认证方式 | 配置变量 | 说明 |\n|---------|---------|------|\n| API Key | `PHOENIX_API_KEY` | Bearer Token 认证 |\n| 自定义 Header | `PHOENIX_CLIENT_HEADERS` | JSON 格式自定义头 |\n| JWT (可选) | 环境变量配置 | 可选的 JWT 验证 |\n\n### 数据隔离\n\n- **项目级隔离**：数据按 Project 隔离\n- **租户隔离**：支持多租户部署\n- **API Key 权限**：系统级和个人级 API Key\n\n## 技术栈汇总\n\n| 层级 | 技术选型 | 版本要求 |\n|-----|---------|---------|\n| 后端框架 | FastAPI | Python 3.8+ |\n| 数据库 ORM | SQLAlchemy | - |\n| 前端框架 | React 18+ | TypeScript 5+ |\n| 状态管理 | Zustand | - |\n| UI 组件库 | Adobe Spectrum | - |\n| 追踪标准 | OpenTelemetry | - |\n| 协议 | REST, GraphQL, gRPC, MCP | - |\n\n## 扩展性设计\n\n### SDK 扩展点\n\n1. **OTEL 处理器**：支持自定义 Span 处理器\n2. **评估器**：可扩展的 LLM 评估框架\n3. **存储后端**：支持多种数据库适配器\n4. **MCP 工具**：可注册的 MCP 工具扩展\n\n### 前端扩展点\n\n| 扩展类型 | 位置 | 说明 |\n|---------|------|------|\n| 路由注册 | Routes.tsx | 新增页面路由 |\n| 组件覆盖 | 各业务组件 | 自定义展示逻辑 |\n| 样式主题 | CSS Variables | 品牌定制 |\n\n资料来源：[app/src/Routes.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/Routes.tsx)\n\n## 总结\n\nPhoenix 系统采用现代化的微服务风格架构设计，通过前后端分离、SDK 多语言支持、标准化的 OpenTelemetry 集成以及灵活的 MCP 扩展机制，为 LLM 应用提供了完整的可观测性解决方案。架构设计注重开发者体验，支持从本地开发到云端托管的多种部署场景。\n\n---\n\n\n\n## 数据库模型与迁移\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-002), [Datasets 与 Experiments 数据管理](#page-006)\n\n由于提供的上下文（START_OF_CONTEXT）中并未包含 `src/phoenix/db/models.py`、`src/phoenix/db/migrations/versions/cf03bd6bae1d_init.py`、`src/phoenix/db/engines.py` 和 `src/phoenix/db/bulk_inserter.py` 等数据库相关源文件，我无法基于这些文件的实际内容生成准确的技术文档。\n\n提供的上下文中仅包含以下类型的文件：\n\n| 文件类型 | 文件路径示例 |\n|---------|-------------|\n| npm 包 README | `js/packages/phoenix-config/README.md`、`js/packages/phoenix-client/README.md` |\n| React 组件 TSX | `app/src/components/project/PythonProjectGuide.tsx` |\n| 配置文件 | `app/package.json` |\n| API 文档说明 | `api_reference/README.md` |\n\n这些文件主要描述了：\n\n- **phoenix-config**：环境变量配置解析工具\n- **phoenix-client**：Python 和 TypeScript 客户端库的使用方法\n- **phoenix-otel**：OpenTelemetry 集成配置\n- **phoenix-evals**：评估库的使用方式\n- **phoenix-cli**：CLI 命令行工具\n\n要完成\"数据库模型与迁移\"这一主题的技术文档，需要访问以下实际数据库源码文件：\n\n
\n缺失的数据库核心源文件\n\n以下文件未在当前上下文中提供，无法进行准确分析：\n\n- `src/phoenix/db/models.py` — ORM 数据模型定义\n- `src/phoenix/db/migrations/versions/cf03bd6bae1d_init.py` — 数据库初始化迁移\n- `src/phoenix/db/engines.py` — 数据库引擎配置\n- `src/phoenix/db/bulk_inserter.py` — 批量数据插入逻辑\n\n
\n\n请提供上述数据库相关源文件的具体内容，或调整查询范围以匹配上下文中已有的文件类型。\n\n---\n\n\n\n## Tracing 系统实现\n\n### 相关页面\n\n相关主题：[Evaluation 评估系统](#page-005), [Python SDK 参考](#page-010)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/phoenix/server/api/helpers/annotations.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/helpers/annotations.py)\n- [src/phoenix/db/insertion/span.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/span.py)\n- [src/phoenix/server/api/dataloaders/span_by_id.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/dataloaders/span_by_id.py)\n- [packages/phoenix-otel/src/phoenix/otel/otel.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-otel/src/phoenix/otel/otel.py)\n- [js/packages/phoenix-otel/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-otel/README.md)\n- [js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n- [src/phoenix/db/README.md](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/README.md)\n
\n\n# Tracing 系统实现\n\n## 概述\n\nPhoenix 的 Tracing 系统是一个完整的可观测性解决方案，用于捕获、分析和可视化 LLM 应用和代理的运行时行为。该系统基于 OpenTelemetry 标准构建，支持多语言客户端（Python 和 TypeScript），能够追踪从简单的函数调用到复杂的多代理工作流。\n\nTracing 的核心作用是记录分布式系统中的请求链路，将每个操作分解为 span（跨度），并关联到对应的项目（Project）和会话（Session）中。资料来源：[src/phoenix/db/README.md]()\n\n## 核心数据模型\n\n### Trace 与 Span 层级结构\n\nPhoenix 使用分层的数据模型来组织追踪数据：\n\n```mermaid\nerDiagram\n Project ||--o{ Trace : has\n Trace ||--o{ Span : contains\n Trace ||--o{ TraceAnnotation : has\n Span ||--o{ SpanAnnotation : has\n Span ||--o{ DocumentAnnotation : has\n```\n\n| 实体 | 描述 | 关联关系 |\n|------|------|----------|\n| **Project** | 追踪项目的顶级容器，用于组织相关的 Trace 数据 | 包含多个 Trace |\n| **Trace** | 单次请求的完整执行链路记录 | 包含多个 Span |\n| **Span** | 追踪中的单个操作单元，记录函数调用或工具执行 | 属于一个 Trace |\n| **SpanAnnotation** | 对 Span 的评估注释，包含正确性、相关性等评估结果 | 关联到用户和 Span |\n| **DocumentAnnotation** | 文档级别的注释，用于 RAG 场景中的文档评估 | 关联到用户和 Span |\n\n资料来源：[src/phoenix/db/README.md]()\n\n### Span 数据结构\n\nSpan 是追踪系统的基本单元，包含以下关键信息：\n\n- **输入/输出消息**：记录函数调用的参数和返回值\n- **时间戳**：操作的开始和结束时间\n- **Token 使用量**：LLM 调用的 token 消耗统计\n- **延迟信息**：操作的响应时间\n- **元数据**：Prompts、Responses 等详细信息\n\n资料来源：[js/examples/apps/langchain-quickstart/README.md]()\n\n## 架构设计\n\n### 系统组件架构\n\n```mermaid\ngraph TD\n A[Application Code] --> B[Phoenix OTEL SDK]\n B --> C[OTLP Exporter]\n C --> D[Phoenix Server]\n D --> E[(Database)]\n \n F[Phoenix Client] --> D\n G[Phoenix Evals] --> D\n H[Phoenix UI] --> D\n \n D --> F\n D --> G\n D --> H\n```\n\n| 组件 | 职责 | 技术栈 |\n|------|------|--------|\n| **Phoenix OTEL SDK** | 在应用程序中收集追踪数据 | Python/TypeScript |\n| **OTLP Exporter** | 通过 OpenTelemetry 协议导出数据 | OpenTelemetry |\n| **Phoenix Server** | 接收、存储和提供追踪数据 | FastAPI/Python |\n| **Phoenix Client** | 提供 Python API 访问追踪数据 | Python |\n| **Phoenix Evals** | 对 Span 进行自动化评估 | LLM-based |\n\n资料来源：[packages/phoenix-otel/src/phoenix/otel/otel.py]()\n\n### OTEL 注册流程\n\nPhoenix OTEL SDK 的核心是 `register()` 函数，用于初始化追踪：\n\n```mermaid\ngraph LR\n A[register config] --> B[Create TracerProvider]\n B --> C[Setup OTLP Exporter]\n C --> D[Register Phoenix]\n D --> E[Return Provider]\n```\n\n**register() 函数配置参数：**\n\n| 参数 | 类型 | 说明 | 示例 |\n|------|------|------|------|\n| `projectName` | string | 项目名称，用于组织追踪数据 | `\"my-llm-app\"` |\n| `url` | string | Phoenix 服务器地址 | `\"https://app.phoenix.arize.com\"` |\n| `apiKey` | string | API 认证密钥 | `process.env.PHOENIX_API_KEY` |\n| `endpoint` | string | OTLP 收集器端点 | `\"http://localhost:6007/v1/traces\"` |\n\n资料来源：[js/packages/phoenix-otel/README.md]()\n\n## 数据加载与查询\n\n### Span 数据加载器\n\nPhoenix Server 提供了 `SpanByID` 数据加载器用于高效获取 Span 数据：\n\n```python\n# 数据加载器接口\nclient.spans.get_spans_dataframe(\n project_identifier=\"my-llm-app\",\n limit=1000,\n root_spans_only=True, # 仅获取顶级 Span\n start_time=datetime.now() - timedelta(hours=24)\n)\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `project_identifier` | string | 必需 | 项目标识符 |\n| `include_spans` | bool | False | 是否包含完整 Span 详情 |\n| `session_id` | str \\| Sequence[str] | None | 按会话 ID 过滤 |\n| `limit` | int | 100 | 最大返回数量 |\n| `timeout` | int | 60 | 请求超时（秒） |\n\n资料来源：[packages/phoenix-client/README.md]()\n\n### 注解数据查询\n\n```python\n# 获取 Span 注解\nannotations_df = client.spans.get_span_annotations_dataframe(\n spans_dataframe=spans_df,\n project_identifier=\"my-llm-app\",\n include_annotation_names=[\"relevance\", \"accuracy\"],\n exclude_annotation_names=[\"note\"]\n)\n```\n\n资料来源：[packages/phoenix-client/README.md]()\n\n## 追踪帮助函数\n\n### TypeScript 追踪工具\n\nPhoenix OTEL 提供了多个追踪辅助函数，简化函数和链路的instrumentation：\n\n| 函数 | 用途 | 典型场景 |\n|------|------|----------|\n| `traceChain()` | 追踪 LangChain/LangGraph 链 | 追踪 LLM 链执行 |\n| `traceAgent()` | 追踪代理执行 | 追踪 AI Agent |\n| `traceTool()` | 追踪工具调用 | 记录外部工具使用 |\n| `observe()` | 通用观测装饰器 | 追踪任意函数 |\n| `withSpan()` | 手动创建 Span | 细粒度控制 |\n\n资料来源：[js/packages/phoenix-otel/README.md]()\n\n### Python 环境变量配置\n\n| 变量 | 常量名 | 描述 |\n|------|--------|------|\n| `PHOENIX_HOST` | `ENV_PHOENIX_HOST` | Phoenix 服务器地址 |\n| `PHOENIX_API_KEY` | `ENV_PHOENIX_API_KEY` | API 认证密钥 |\n| `PHOENIX_COLLECTOR_ENDPOINT` | `ENV_PHOENIX_COLLECTOR_ENDPOINT` | OTLP 收集器端点 |\n| `PHOENIX_PORT` | `ENV_PHOENIX_PORT` | HTTP 端口 |\n| `PHOENIX_GRPC_PORT` | `ENV_PHOENIX_GRPC_PORT` | gRPC 端口 |\n| `PHOENIX_PROJECT` | `ENV_PHOENIX_PROJECT` | 默认项目名称 |\n\n资料来源：[js/packages/phoenix-config/README.md]()\n\n## 注解系统\n\n### 注解配置\n\nPhoenix 支持为项目配置多种类型的注解：\n\n```mermaid\nerDiagram\n Project ||--o{ ProjectAnnotationConfig : has\n AnnotationConfig ||--o{ ProjectAnnotationConfig : configures\n User ||--o{ SpanAnnotation : creates\n User ||--o{ DocumentAnnotation : creates\n User ||--o{ TraceAnnotation : creates\n```\n\n### 注解数据流\n\n```mermaid\ngraph TD\n A[Evaluation Run] --> B[Fetch Spans]\n B --> C[Run LLM Evaluator]\n C --> D[Create Annotations]\n D --> E[Store in DB]\n E --> F[Display in UI]\n```\n\n### 内置评估器\n\nPhoenix 提供了预构建的正确性评估器：\n\n```typescript\n// 预构建评估器\nconst result = await runnableCorrectness评估(spans, {\n rubric: \"travel_rubric\",\n model: fireworksModel\n});\n```\n\n资料来源：[js/examples/apps/langchain-quickstart/README.md]()\n\n## UI 可视化\n\n### Trace 视图\n\nPhoenix UI 提供了完整的 Trace 可视化功能：\n\n- **LangGraph 追踪**：显示代理的整体执行链路\n- **工具调用详情**：展示 essential_info、budget_basics、local_flavor 等工具的执行\n- **Token 使用统计**：记录每个 LLM 调用的 token 消耗\n- **延迟分析**：显示各操作的响应时间\n- **评估注释**：在 Trace 上直接展示正确性评分\n\n资料来源：[js/examples/apps/langchain-quickstart/README.md]()\n\n### 文档注释\n\n在 RAG 场景中，每个检索到的文档都有独立的注释区域：\n\n```typescript\n\n```\n\n资料来源：[app/src/pages/trace/DocumentItem.tsx]()\n\n## 快速开始\n\n### TypeScript 集成\n\n```typescript\nimport { register, traceChain } from \"@arizeai/phoenix-otel\";\n\nconst provider = register({\n projectName: \"my-app\",\n});\n\nconst answerQuestion = traceChain(\n async (question: string) => `Handled: ${question}`,\n { name: \"answer-question\" }\n);\n\nawait answerQuestion(\"What is Phoenix?\");\nawait provider.shutdown();\n```\n\n### Python OTEL 设置\n\n```bash\npip install arize-phoenix-otel\n```\n\n```python\nimport os\nfrom phoenix.otel import register\n\n# 自动从环境变量读取配置\nos.environ[\"PHOENIX_HOST\"] = \"http://localhost:6006\"\n\nregister(project_name=\"my-project\")\n```\n\n资料来源：[app/src/components/project/PythonProjectGuide.tsx]()\n\n## 相关文档\n\n- [Phoenix OTEL SDK](../js/packages/phoenix-otel/README.md)\n- [Phoenix Client API](../packages/phoenix-client/README.md)\n- [Phoenix Evals](../js/packages/phoenix-evals/README.md)\n- [API 参考文档](../api_reference/README.md)\n\n---\n\n\n\n## Evaluation 评估系统\n\n### 相关页面\n\n相关主题：[Tracing 系统实现](#page-004), [Datasets 与 Experiments 数据管理](#page-006)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [js/packages/phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n- [js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n- [js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n- [app/src/pages/project/SpansTable.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/SpansTable.tsx)\n- [app/src/components/trace/AnnotationConfigList.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/trace/AnnotationConfigList.tsx)\n- [app/src/pages/example/ExampleExperimentRunsTable.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/example/ExampleExperimentRunsTable.tsx)\n- [app/src/components/agent/ToolPart.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/ToolPart.tsx)\n- [app/src/components/agent/DocsToolDetails.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/DocsToolDetails.tsx)\n
\n\n# Evaluation 评估系统\n\n## 概述\n\nPhoenix 的 Evaluation（评估）系统是一个用于评估 LLM 应用输出质量的核心模块。该系统提供了基于 LLM 的自动评估能力，支持幻觉检测、相关性评分、二分类和多分类等评估任务。\n\n评估系统在架构上分为前后端两部分：\n\n- **前端**：React 组件负责展示评估配置、评估结果和注解标注界面\n- **后端**：Python API 提供评估器的注册、配置和管理功能\n- **客户端库**：`@arizeai/phoenix-evals` TypeScript 包提供独立的评估能力\n\n资料来源：[js/packages/phoenix-evals/README.md:1-30](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n\n## 核心架构\n\n### 系统组件关系图\n\n```mermaid\ngraph TD\n A[用户应用] --> B[Phoenix Client]\n B --> C[Traces 数据]\n C --> D[Span Annotations]\n C --> E[Trace Annotations]\n D --> F[Retrieval Metrics]\n F --> G[评估结果展示]\n E --> G\n H[评估配置] --> I[AnnotationConfigList]\n I --> J[AnnotationSummaryGroupTokens]\n G --> J\n```\n\n### 评估类型分类\n\n评估系统支持多种评估类型，主要分为：\n\n| 评估类型 | 说明 | 支持指标 |\n|---------|------|---------|\n| **分类评估** | 二分类或多分类任务 | 准确率、精确率、召回率 |\n| **检索评估** | RAG 检索质量评估 | NDCG、Precision、Hit |\n| **正确性评估** | 答案正确性判断 | 正确/错误 |\n| **幻觉检测** | 检测生成内容中的虚假信息 | 存在/不存在幻觉 |\n\n资料来源：[app/src/pages/project/SpansTable.tsx:180-210](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/SpansTable.tsx)\n\n## 评估器实现\n\n### 创建分类评估器\n\n`@arizeai/phoenix-evals` 包提供了 `createClassifier` 函数，用于创建自定义评估器：\n\n```typescript\nimport { createClassifier } from \"@arizeai/phoenix-evals/llm\";\nimport { openai } from \"@ai-sdk/openai\";\n\nconst model = openai(\"gpt-4o-mini\");\n\nconst classifier = createClassifier({\n model,\n evaluatorName: \"hallucination-detector\",\n promptTemplate: `\n In this task, you will be presented with a query, a reference text and an answer. \n The answer is generated to the question based on the reference text. \n The answer may contain false information. You must use the reference text \n to determine if the answer to the question contains false information.\n `,\n});\n```\n\n资料来源：[js/packages/phoenix-evals/README.md:25-45](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n\n### 评估器工作流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户应用\n participant C as Classifier\n participant M as LLM Model\n participant P as Phoenix Server\n \n U->>C: 传入 Input + Reference\n C->>M: 发送评估 Prompt\n M-->>C: 返回评估结果\n C-->>U: 返回分类标签\n U->>P: 上报评估结果作为 Annotation\n P-->>U: 存储并返回更新\n```\n\n## 评估注解系统\n\n### 注解配置管理\n\n评估注解通过 `AnnotationConfigList` 组件进行管理：\n\n```typescript\n// 注解配置列表数据结构\n{\n id: string,\n name: string,\n annotationType: \"human\" | \"llm\" | \"api\"\n}\n```\n\n资料来源：[app/src/components/trace/AnnotationConfigList.tsx:1-50](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/trace/AnnotationConfigList.tsx)\n\n### 注解显示组件\n\n评估结果通过以下组件层级展示：\n\n| 组件 | 用途 |\n|-----|------|\n| `AnnotationSummaryGroupTokens` | 显示 span 层级的注解摘要 |\n| `TraceAnnotationSummaryGroupTokens` | 显示 trace 层级的注解摘要 |\n| `AnnotationLabel` | 单个注解标签展示 |\n| `RetrievalEvaluationLabel` | 检索评估指标标签 |\n\n资料来源：[app/src/pages/project/SpansTable.tsx:150-230](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/SpansTable.tsx)\n\n### 检索评估指标\n\n检索评估支持以下三个标准指标：\n\n| 指标名 | 说明 | 数据类型 |\n|-------|------|---------|\n| `ndcg` | 归一化折扣累计增益 | float |\n| `precision` | 精确率 | float |\n| `hit` | 命中标记 | boolean |\n\n```typescript\n{row.original.documentRetrievalMetrics.map((retrievalMetric) => {\n return (\n <>\n \n \n \n \n );\n})}\n```\n\n资料来源：[app/src/pages/project/SpansTable.tsx:190-215](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/SpansTable.tsx)\n\n## 实验运行评估\n\n### 评估追踪\n\n评估结果与实验运行关联，支持在 `ExampleExperimentRunsTable` 中查看评估追踪：\n\n```typescript\n// 评估追踪数据结构\n{\n annotation: {\n name: string,\n label: string,\n score?: number,\n trace?: {\n projectId: string,\n traceId: string\n }\n }\n}\n```\n\n点击评估标签可导航到对应的 trace 详情页面：\n\n```typescript\nonClick={() => {\n if (annotation.trace) {\n navigate(\n `/projects/${annotation.trace.projectId}/traces/${annotation.trace.traceId}`\n );\n }\n}}\n```\n\n资料来源：[app/src/pages/example/ExampleExperimentRunsTable.tsx:1-80](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/example/ExampleExperimentRunsTable.tsx)\n\n## 工具输出评估\n\n### 工具调用状态\n\n评估系统也用于标注工具调用的输出状态：\n\n| 状态 | 说明 |\n|-----|------|\n| `input-available` | 输入已提供 |\n| `output-available` | 输出已生成 |\n| `output-error` | 执行出错 |\n\n```typescript\n{part.state === \"output-available\" ? (\n <>\n Output\n {outputStr}\n \n) : null}\n{part.state === \"output-error\" ? (\n <>\n Error\n {part.errorText ?? \"\"}\n \n) : null}\n```\n\n资料来源：[app/src/components/agent/ToolPart.tsx:1-60](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/ToolPart.tsx)\n\n### 文档工具评估\n\n文档搜索工具支持特殊的输出格式评估：\n\n```typescript\nexport function truncateDocsOutput(text: string): string {\n if (text.length <= OUTPUT_PREVIEW_LENGTH) {\n return text;\n }\n return text.slice(0, OUTPUT_PREVIEW_LENGTH) + \"…\";\n}\n```\n\n资料来源：[app/src/components/agent/DocsToolDetails.tsx:1-60](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/DocsToolDetails.tsx)\n\n## 环境配置\n\n### Phoenix 配置变量\n\n评估系统依赖以下环境变量进行配置：\n\n| 变量名 | 用途 | 示例值 |\n|-------|------|--------|\n| `PHOENIX_HOST` | Phoenix 服务地址 | `http://localhost:6006` |\n| `PHOENIX_API_KEY` | API 认证密钥 | `...` |\n| `PHOENIX_PROJECT` | 默认项目名称 | `my-project` |\n| `PHOENIX_COLLECTOR_ENDPOINT` | OTEL 收集器地址 | `http://localhost:4317` |\n\n资料来源：[js/packages/phoenix-config/README.md:20-35](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n### 客户端配置\n\n使用 Phoenix 客户端连接评估服务：\n\n```bash\n# 安装客户端\nnpm install @arizeai/phoenix-client\n\n# 配置连接\nPHOENIX_HOST='http://localhost:12345' \nPHOENIX_API_KEY='xxxxxx' \npnpx tsx examples/list_datasets.ts\n```\n\n```typescript\nimport { Client } from \"@arizeai/phoenix-client\";\n\nconst client = new Client();\n// 自动从环境变量读取配置\n```\n\n资料来源：[js/packages/phoenix-client/README.md:1-40](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n\n## 安装依赖\n\n### Python 环境\n\n```bash\npip install arize-phoenix-otel\npip install arize-phoenix-client\n```\n\n### JavaScript/TypeScript 环境\n\n```bash\nnpm install @arizeai/phoenix-evals\nnpm install @arizeai/phoenix-client\nnpm install @arizeai/phoenix-config\n```\n\n资料来源：[app/src/components/project/PythonProjectGuide.tsx:1-30](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n\n## 数据流总览\n\n```mermaid\nflowchart LR\n subgraph 应用层\n A[用户应用] --> B[Phoenix OTEL]\n A --> C[Phoenix Client]\n end\n \n subgraph 评估层\n B --> D[Traces]\n C --> E[Datasets]\n D --> F[Spans]\n F --> G[Span Annotations]\n G --> H[Retrieval Metrics]\n E --> I[Evaluations]\n end\n \n subgraph 展示层\n G --> J[AnnotationSummary]\n H --> J\n I --> K[Experiment Runs]\n K --> L[Evaluation Labels]\n end\n```\n\n## 最佳实践\n\n### 评估配置建议\n\n1. **使用 LLM 评估器**：利用 `createClassifier` 创建领域特定的评估器\n2. **配置检索指标**：为 RAG 应用配置 NDCG、Precision 和 Hit 指标\n3. **关联 Trace**：确保评估结果与对应的 trace 正确关联\n4. **设置阈值**：根据业务需求设置评估分数阈值\n\n### 性能优化\n\n- 批量处理评估请求减少 API 调用\n- 使用流式处理处理大型文档评估\n- 缓存常用的评估 Prompt 模板\n\n---\n\n\n\n## Datasets 与 Experiments 数据管理\n\n### 相关页面\n\n相关主题：[Evaluation 评估系统](#page-005), [Prompt Playground 与管理](#page-007)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/phoenix/db/insertion/dataset.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/dataset.py)\n- [src/phoenix/server/api/input_types/CreateDatasetInput.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/input_types/CreateDatasetInput.py)\n- [src/phoenix/server/api/helpers/dataset_helpers.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/helpers/dataset_helpers.py)\n- [packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py)\n- [js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n- [app/src/components/experiment/RunExperimentCodeDialog.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/experiment/RunExperimentCodeDialog.tsx)\n
\n\n# Datasets 与 Experiments 数据管理\n\n## 概述\n\nPhoenix 的 Datasets 与 Experiments 模块构成了一个完整的数据管理和实验执行框架。该系统允许用户创建数据集（Dataset）来存储示例数据，并通过实验（Experiment）对数据集进行任务执行和评估。\n\n**核心功能：**\n\n- **数据集管理**：创建、读取、更新、删除数据集\n- **示例管理**：为数据集添加输入（input）、输出（output）和元数据（metadata）\n- **实验执行**：基于数据集运行任务并收集结果\n- **评估系统**：通过评估器（Evaluator）对实验结果进行评分\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py:1-50]()\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[Phoenix Client] --> B[REST API]\n B --> C[Dataset Service]\n C --> D[(PostgreSQL Database)]\n \n E[Experiments API] --> C\n F[Experiment Runners] --> E\n \n G[Evaluators] --> E\n \n D --> H[Traces & Spans]\n D --> I[Annotations]\n```\n\n### 数据流架构\n\n```mermaid\ngraph LR\n A[Create Dataset] --> B[Add Examples]\n B --> C[Run Experiment]\n C --> D[Define Task]\n D --> E[Apply Evaluators]\n E --> F[Collect Results]\n F --> G[View Annotations]\n```\n\n资料来源：[js/packages/phoenix-client/README.md:1-80]()\n\n## 数据集（Dataset）模型\n\n### 数据结构\n\n每个 Dataset 包含以下核心字段：\n\n| 字段名 | 类型 | 描述 | 必需 |\n|--------|------|------|------|\n| `name` | string | 数据集名称 | 是 |\n| `description` | string | 数据集描述 | 否 |\n| `examples` | Example[] | 示例数组 | 是 |\n| `version_id` | string | 数据集版本ID | 否 |\n| `metadata` | dict | 附加元数据 | 否 |\n\n### 示例（Example）结构\n\n| 字段名 | 类型 | 描述 | 必需 |\n|--------|------|------|------|\n| `input` | dict | 输入数据，键值对形式 | 是 |\n| `output` | dict | 预期输出数据 | 是 |\n| `metadata` | dict | 示例级元数据 | 否 |\n| `split` | string | 数据集划分（train/test/eval） | 否 |\n\n资料来源：[src/phoenix/server/api/input_types/CreateDatasetInput.py:1-30]()\n\n### Python SDK 数据模型\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# 创建数据集示例\ndataset = client.datasets.create(\n name=\"my-dataset\",\n description=\"数据集描述\",\n examples=[\n {\n \"input\": {\"question\": \"What is the capital of France?\"},\n \"output\": {\"answer\": \"Paris\"},\n \"metadata\": {\"difficulty\": \"easy\"}\n }\n ]\n)\n```\n\n资料来源：[packages/phoenix-client/README.md:40-70]()\n\n## 数据集操作 API\n\n### 创建数据集\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# 基础创建\ndataset = client.datasets.create(\n name=\"questions\",\n description=\"问题数据集\",\n examples=[\n {\n \"input\": {\"question\": \"What is the capital of France\"},\n \"output\": {\"answer\": \"Paris\"},\n \"metadata\": {}\n }\n ]\n)\n\n# 获取返回的 dataset_id\ndataset_id = dataset[\"id\"]\n```\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py:50-80]()\n\n### 获取数据集\n\n```python\n# 通过 ID 获取\ndataset = client.datasets.get_dataset(\n dataset=\"dataset-id-string\",\n version_id=\"optional-version-id\" # 可选，指定版本\n)\n\n# 列出所有数据集\ndatasets = client.datasets.list_datasets()\n```\n\n### 更新数据集\n\n```python\n# 添加新示例\nupdated_dataset = client.datasets.upsert_dataset(\n dataset=\"dataset-id-or-name\",\n examples=[\n {\n \"input\": {\"question\": \"What is the capital of the USA\"},\n \"output\": {\"answer\": \"Washington D.C.\"},\n \"metadata\": {}\n }\n ]\n)\n```\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py:100-150]()\n\n### 插入参数说明\n\n| 参数名 | 类型 | 描述 |\n|--------|------|------|\n| `dataset` | str \\| Dataset object | 数据集标识符或对象 |\n| `examples` | List[dict] | 要添加的示例列表 |\n| `input_keys` | List[str] | 用作输入键的列名 |\n| `output_keys` | List[str] | 用作输出键的列名 |\n| `metadata_keys` | List[str] | 用作元数据键的列名 |\n| `split_key` | str \\| None | 用于划分示例的列名 |\n| `timeout` | int \\| None | 请求超时时间（秒） |\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py:80-120]()\n\n## 实验（Experiment）系统\n\n### 实验工作流\n\n```mermaid\ngraph TD\n A[创建或获取 Dataset] --> B[定义 Task 函数]\n B --> C[定义 Evaluators]\n C --> D[执行 runExperiment]\n D --> E[收集结果]\n E --> F[查看 Annotations]\n \n G[Task Function] --> H[对每个 Example 执行]\n H --> I[返回实际输出]\n \n J[Evaluators] --> K[评估输出质量]\n K --> L[生成分数/标签]\n```\n\n资料来源：[js/packages/phoenix-client/README.md:80-150]()\n\n### TypeScript 实验执行示例\n\n```typescript\nimport { createDataset } from \"@arizeai/phoenix-client/datasets\";\nimport { asExperimentEvaluator, runExperiment } from \"@arizeai/phoenix-client/experiments\";\n\n// 1. 创建数据集\nconst { datasetId } = await createDataset({\n name: \"names-dataset\",\n description: \"名字数据集\",\n examples: [\n {\n input: { name: \"John\" },\n output: { text: \"Hello, John!\" },\n metadata: {}\n }\n ]\n});\n\n// 2. 定义任务函数\nconst task = async (example) => `hello ${example.input.name}`;\n\n// 3. 定义评估器\nconst evaluators = [\n asExperimentEvaluator({\n name: \"matches\",\n kind: \"CODE\",\n evaluate: async ({ output, expected }) => {\n return { correct: output === expected };\n }\n })\n];\n\n// 4. 运行实验\nconst results = await runExperiment({\n datasetId,\n task,\n evaluators,\n experimentName: \"my-first-experiment\"\n});\n```\n\n资料来源：[js/packages/phoenix-client/README.md:100-160]()\n\n### Python 实验执行\n\n```python\nfrom phoenix.client import Client\nfrom phoenix.experiments import run_experiment\n\nclient = Client()\n\n# 运行实验\nresults = run_experiment(\n experiment_name=\"evaluation-run\",\n dataset_name=\"my-dataset\",\n task=my_task_function,\n evaluators=[accuracy_evaluator, relevance_evaluator]\n)\n\n# 查看结果\nprint(results.metrics)\nprint(results.traces)\n```\n\n## 评估器（Evaluator）系统\n\n### 评估器类型\n\n| 类型 | 描述 | 使用场景 |\n|------|------|----------|\n| `CODE` | 代码执行的确定性评估 | 精确匹配、包含检查 |\n| `LLM` | 基于大语言模型的评估 | 开放性问答、内容质量 |\n| `HUMAN` | 人工标注评估 | 主观判断、敏感内容 |\n\n### 内置评估器\n\nPhoenix 提供了预构建的评估器，包括：\n\n- **准确性评估器**：检查输出是否正确\n- **相关性评估器**：评估与输入的相关程度\n- **文档相关性分类**：判断文档是否回答了问题\n\n资料来源：[src/phoenix/__generated__/classification_evaluator_configs/_document_relevance_classification_evaluator_config.py:1-40]()\n\n### 自定义评估器\n\n```python\nfrom phoenix.experiments import Evaluator\n\nmy_evaluator = Evaluator(\n name=\"custom_eval\",\n evaluate_fn=async def evaluate(example, output):\n # 自定义评估逻辑\n score = calculate_score(output)\n return {\"score\": score, \"label\": \"good\" if score > 0.8 else \"poor\"}\n)\n```\n\n## API 端点参考\n\n### REST API\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/v1/datasets` | POST | 创建数据集 |\n| `/v1/datasets/{id}` | GET | 获取数据集详情 |\n| `/v1/datasets` | GET | 列出所有数据集 |\n| `/v1/datasets/{id}/examples` | POST | 添加示例 |\n| `/v1/experiments` | POST | 运行实验 |\n\n### 获取 Span 数据\n\n```python\nfrom phoenix.client import Client\nfrom datetime import datetime, timedelta\n\nclient = Client()\n\n# 获取 spans 作为 DataFrame\nspans_df = client.spans.get_spans_dataframe(\n project_identifier=\"my-llm-app\",\n limit=1000,\n root_spans_only=True,\n start_time=datetime.now() - timedelta(hours=24)\n)\n\n# 获取 span 标注\nannotations_df = client.spans.get_span_annotations_dataframe(\n spans_dataframe=spans_df,\n project_identifier=\"my-llm-app\",\n include_annotation_names=[\"relevance\", \"accuracy\"]\n)\n```\n\n资料来源：[packages/phoenix-client/README.md:150-200]()\n\n## 认证与授权\n\n### API Key 配置\n\n当启用认证时，需要配置 API Key：\n\n```python\n# 环境变量方式\nimport os\nos.environ[\"PHOENIX_API_KEY\"] = \"your-api-key\"\n\n# 或初始化时指定\nclient = Client(\n api_key=\"your-api-key\",\n endpoint=\"http://localhost:6006\"\n)\n```\n\n### OTEL SDK 认证\n\n```bash\n# 使用 Bearer Token\nOTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer your-api-key'\n```\n\n资料来源：[app/src/components/auth/OneTimeAPIKeyDialog.tsx:50-80]()\n\n## 最佳实践\n\n### 数据集设计\n\n1. **清晰的输入输出结构**：使用一致的 JSON 结构\n2. **充分的元数据**：添加有助于分析的元数据\n3. **版本控制**：使用版本ID追踪数据集变更\n4. **合理划分**：使用 split_key 进行 train/test/eval 划分\n\n### 实验设计\n\n1. **单一职责任务**：每个任务函数只做一件事\n2. **可组合评估器**：将复杂评估拆分为多个评估器\n3. **结果追踪**：使用 experiment_name 命名便于追踪\n4. **批量处理**：利用异步执行提高效率\n\n### 代码生成示例\n\nPhoenix 提供交互式代码生成功能，帮助用户快速上手：\n\n```python\n# 在 UI 中选择数据集后自动生成的代码\nimport arize_phoenix as phoenix\n\nclient = phoenix.Client()\n\n# 获取数据集\ndataset = client.datasets.get_dataset(\n dataset=\"my-dataset-name\",\n version_id=\"optional-version-id\"\n)\n\n# 数据集现已可用于实验\n```\n\n资料来源：[app/src/components/experiment/RunExperimentCodeDialog.tsx:1-50]()\n\n## 总结\n\nPhoenix 的 Datasets 与 Experiments 系统为 LLM 应用评估提供了完整的数据管理和实验执行能力。通过标准化的数据集结构、灵活的评估器系统和丰富的客户端支持，开发者可以高效地进行模型评估和迭代优化。\n\n该系统支持：\n\n- **多语言客户端**：Python、TypeScript/JavaScript\n- **丰富的评估方法**：代码评估、LLM 评估、人工评估\n- **完整的实验追踪**：记录每次运行的结果和标注\n- **灵活的部署选项**：本地部署或云端服务\n\n---\n\n\n\n## Prompt Playground 与管理\n\n### 相关页面\n\n相关主题：[Datasets 与 Experiments 数据管理](#page-006), [数据库模型与迁移](#page-003)\n\n# Prompt Playground 与管理\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [app/src/pages/playground/Playground.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/playground/Playground.tsx)\n- [src/phoenix/server/api/helpers/prompts/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/helpers/prompts/__init__.py)\n- [src/phoenix/server/api/helpers/prompts/conversions/openai.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/helpers/prompts/conversions/openai.py)\n- [packages/phoenix-client/src/phoenix/client/resources/prompts/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/prompts/__init__.py)\n- [js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n
\n\n## 概述\n\nPhoenix 的 Prompt Playground 是一个交互式环境，用于测试、调试和管理 LLM（大型语言模型）提示词。该功能允许开发者：\n\n- 实时编辑和测试提示词\n- 查看模型响应\n- 管理多个提示词版本\n- 与 Phoenix 的追踪和评估系统集成\n\n## 核心架构\n\n```mermaid\ngraph TD\n A[Prompt Playground UI] --> B[Phoenix Client SDK]\n B --> C[Phoenix API]\n C --> D[Prompt 管理服务]\n D --> E[OpenAI 兼容转换层]\n E --> F[后端 LLM 提供商]\n \n G[追踪系统] --> C\n H[评估系统] --> C\n```\n\n## 提示词管理 API\n\nPhoenix 提供了 Python 和 TypeScript 两种 SDK 方式来管理提示词。\n\n### Python SDK\n\n```python\nimportarize-phoenix-client\n\nclient = Client()\nprompts = client.prompts\n```\n\n### TypeScript SDK\n\n```typescript\nimport { Client } from \"@arizeai/phoenix-client\";\n\nconst client = new Client({\n host: process.env.PHOENIX_HOST,\n apiKey: process.env.PHOENIX_API_KEY,\n});\n```\n\n## 环境配置\n\nPhoenix Client 支持以下环境变量进行配置：\n\n| 变量名 | 说明 |\n|--------|------|\n| `PHOENIX_HOST` | Phoenix 服务器地址 |\n| `PHOENIX_API_KEY` | API 认证密钥 |\n| `PHOENIX_CLIENT_HEADERS` | 自定义请求头（JSON 格式） |\n\n## 与 OpenTelemetry 集成\n\nPrompt Playground 与 Phoenix 的追踪系统紧密集成。通过配置 OpenTelemetry，可以自动记录：\n\n- 提示词输入和输出\n- Token 使用量\n- 延迟信息\n- 模型响应元数据\n\n```python\nfrom phoenix.otel import register\n\nregister(\n project_name=\"prompt-playground\",\n endpoint=\"http://localhost:6007/v1/traces\"\n)\n```\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\n# Python\npip install arize-phoenix-client\n\n# TypeScript\nnpm install @arizeai/phoenix-client\n```\n\n### 2. 配置环境变量\n\n```bash\nexport PHOENIX_HOST=\"http://localhost:6006\"\nexport PHOENIX_API_KEY=\"your-api-key\"\n```\n\n### 3. 访问 Playground\n\n启动 Phoenix 后，在浏览器中访问：\n\n```\nhttp://localhost:6006/playground\n```\n\n## 相关资源\n\n- 官方文档：https://arize-ai.github.io/phoenix/\n- GitHub 仓库：https://github.com/Arize-ai/phoenix\n- Slack 社区：https://join.slack.com/t/arize-ai/shared_invite/zt-3r07iavnk-ammtATWSlF0pSrd1DsMW7g\n\n---\n\n\n\n## 前端组件架构\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-002), [部署配置与容器化](#page-009)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [app/src/App.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/App.tsx)\n- [app/src/Routes.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/Routes.tsx)\n- [app/src/pages/TracingRoot.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/TracingRoot.tsx)\n- [app/src/components/trace/TraceTree.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/trace/TraceTree.tsx)\n- [app/src/store/tracingStore.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/store/tracingStore.tsx)\n- [app/src/pages/project/OnboardingSteps.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/OnboardingSteps.tsx)\n- [app/src/components/project/TypeScriptProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/TypeScriptProjectGuide.tsx)\n- [app/src/components/project/PythonProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n- [app/src/components/markdown/streamdownComponents.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/markdown/streamdownComponents.tsx)\n
\n\n# 前端组件架构\n\n## 概述\n\nPhoenix 前端是一个基于 React 的单页应用（SPA），采用 TypeScript 开发，使用 React Router 进行路由管理。该应用主要负责可视化 LLM 应用产生的追踪数据（Traces）、管理项目配置、以及提供评估和实验功能。前端架构遵循组件化设计原则，通过 Zustand 进行状态管理，并使用 Apollo Client 与后端 GraphQL API 通信。\n\n架构的核心目标是提供一个直观的界面，让开发者能够深入了解其 AI 应用的运行时行为，包括追踪调用链、查看 span 详情、分析标注结果等。\n\n---\n\n## 整体架构\n\nPhoenix 前端采用分层架构设计，主要分为以下几个层次：\n\n```mermaid\ngraph TD\n A[App 入口层] --> B[Routes 路由层]\n B --> C[Pages 页面层]\n C --> D[Components 组件层]\n C --> E[Store 状态层]\n D --> F[UI 基础组件]\n D --> G[业务组件]\n E --> H[Zustand Store]\n G --> I[trace/trace 组件]\n G --> J[project/ 项目组件]\n G --> K[markdown/ 渲染组件]\n```\n\n### 层级说明\n\n| 层级 | 职责 | 关键文件 |\n|------|------|----------|\n| **入口层** | 应用初始化、Provider 配置 | `App.tsx` |\n| **路由层** | 路由定义、懒加载 | `Routes.tsx` |\n| **页面层** | 业务页面编排 | `TracingRoot.tsx`, `ProjectTracesPage.tsx` |\n| **组件层** | UI 组件实现 | 各类 `*.tsx` 组件 |\n| **状态层** | 全局状态管理 | `tracingStore.tsx` |\n\n---\n\n## 核心模块\n\n### 1. 路由系统\n\nPhoenix 前端使用 React Router v6 定义应用路由结构。路由配置采用声明式写法，支持嵌套路由和懒加载模式。\n\n资料来源：[app/src/Routes.tsx:1-80](https://github.com/Arize-ai/phoenix/blob/main/app/src/Routes.tsx)\n\n#### 路由配置结构\n\n```mermaid\ngraph LR\n A[/projects] --> B[ProjectLayout]\n B --> C[traces]\n B --> D[evaluations]\n B --> E[prompts]\n B --> F[datasets]\n A --> G[/settings]\n G --> G1[general]\n G --> G2[secrets]\n G --> G3[providers]\n G --> G4[models]\n```\n\n核心路由包括：\n\n| 路径 | 页面组件 | 功能 |\n|------|----------|------|\n| `/projects/:projectId/traces` | `ProjectTracesPage` | 追踪列表与详情 |\n| `/projects/:projectId/evaluations` | 评估页面 | 评估结果管理 |\n| `/projects/:projectId/prompts` | 提示工程页面 | Prompt 版本管理 |\n| `/projects/:projectId/datasets` | 数据集页面 | 数据集编辑 |\n| `/settings/*` | 设置相关页面 | 系统配置 |\n\n#### 路由代码示例\n\n```typescript\n}\n handle={{\n crumb: () => \"Settings\",\n }}\n>\n }\n />\n\n```\n\n资料来源：[app/src/Routes.tsx:45-55](https://github.com/Arize-ai/phoenix/blob/main/app/src/Routes.tsx)\n\n### 2. 追踪根组件\n\n`TracingRoot` 是追踪功能的核心容器组件，负责提供追踪上下文环境。该组件使用 React Context 模式，将追踪相关的状态和操作向下传递给子组件。\n\n资料来源：[app/src/pages/TracingRoot.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/TracingRoot.tsx)\n\n```mermaid\ngraph TD\n A[TracingRoot] --> B[TracePaginationProvider]\n A --> C[SpanFiltersProvider]\n B --> D[TracesTable]\n C --> E[Span 相关组件]\n D --> F[AnnotationTooltip]\n D --> G[AnnotationLabel]\n```\n\n#### TracingRoot 结构\n\n```typescript\nexport const ProjectTracesPage = () => {\n return (\n \n \n \n }>\n \n \n \n \n \n \n \n \n );\n};\n```\n\n资料来源：[app/src/pages/TracingRoot.tsx:60-75](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/TracingRoot.tsx)\n\n### 3. 状态管理\n\nPhoenix 前端使用 Zustand 作为状态管理方案。`tracingStore` 是追踪功能的核心状态存储，管理追踪数据的加载、分页、过滤等状态。\n\n资料来源：[app/src/store/tracingStore.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/store/tracingStore.tsx)\n\n#### 状态管理架构\n\n```mermaid\ngraph LR\n A[用户操作] --> B[tracingStore]\n B --> C[API 调用]\n C --> D[更新状态]\n D --> E[触发 UI 渲染]\n```\n\n#### Store 核心功能\n\n| 功能 | 说明 |\n|------|------|\n| 分页管理 | 管理追踪记录的分页状态 |\n| 过滤条件 | 存储和应用 span 过滤条件 |\n| 查询状态 | 追踪 GraphQL 查询引用 |\n| 选中状态 | 当前选中的 trace/spand ID |\n\n### 4. 追踪树组件\n\n`TraceTree` 组件负责渲染追踪数据的树形结构，展示 trace 与 span 之间的层级关系。\n\n资料来源：[app/src/components/trace/TraceTree.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/trace/TraceTree.tsx)\n\n```mermaid\ngraph TD\n A[TraceTree] --> B[TraceRow]\n A --> C[SpanRow]\n B --> D[展开/折叠]\n C --> E[层级缩进]\n B --> F[元数据展示]\n```\n\n#### 树节点数据结构\n\n```typescript\ninterface TraceNode {\n id: string;\n traceId: string;\n projectId: string;\n children?: TraceNode[];\n metadata: SpanMetadata;\n}\n```\n\n---\n\n## 业务组件\n\n### 1. 项目引导组件\n\n`OnboardingSteps` 是新用户首次使用时的引导组件，帮助用户完成 Phoenix 的初始配置。\n\n资料来源：[app/src/pages/project/OnboardingSteps.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/OnboardingSteps.tsx)\n\n#### 组件 Props\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `language` | `ProgrammingLanguage` | 编程语言类型 |\n| `packages` | `readonly string[]` | 需安装的包列表 |\n| `implementationCode` | `string` | 示例实现代码 |\n| `docsHref` | `string` | 文档链接 |\n| `githubHref` | `string` | GitHub 链接 |\n| `generatedApiKey` | `string \\| null` | 生成的 API Key |\n| `onApiKeyGenerated` | `(key: string) => void` | API Key 生成回调 |\n\n#### 组件功能\n\n1. **环境变量配置**：根据认证状态和部署类型生成相应的环境变量\n2. **文档链接**：提供指向官方文档和 GitHub 的外部链接\n3. **API Key 生成**：支持在托管部署环境下生成项目 API Key\n\n```typescript\nconst envVars = getEnvironmentVariables({\n isAuthEnabled,\n isHosted,\n apiKey: generatedApiKey ?? undefined,\n extraEnvVars,\n});\n```\n\n资料来源：[app/src/pages/project/OnboardingSteps.tsx:75-80](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/OnboardingSteps.tsx)\n\n### 2. 项目指南组件\n\nPhoenix 提供针对不同编程语言的项目设置指南组件。\n\n#### TypeScript 项目指南\n\n资料来源：[app/src/components/project/TypeScriptProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/TypeScriptProjectGuide.tsx)\n\n```mermaid\ngraph TD\n A[TypeScriptProjectGuide] --> B[Quick Start 区块]\n A --> C[环境变量区块]\n A --> D[API Key 生成区块]\n B --> E[TypeScript 代码块]\n C --> F[Bash 代码块]\n```\n\n**核心功能：**\n\n- 展示 OpenTelemetry 初始化代码\n- 提供环境变量配置示例\n- 根据认证状态显示 API Key 管理入口\n\n#### Python 项目指南\n\n资料来源：[app/src/components/project/PythonProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n\n**安装依赖部分：**\n\n```typescript\n\n```\n\n**环境变量配置：**\n\n组件自动从环境变量读取配置，无需手动设置。支持的变量包括：\n\n| 变量名 | 用途 |\n|--------|------|\n| `PHOENIX_HOST` | Phoenix 服务器地址 |\n| `PHOENIX_API_KEY` | API 认证密钥 |\n| `PHOENIX_PORT` | HTTP 端口 |\n| `PHOENIX_GRPC_PORT` | gRPC 端口 |\n| `PHOENIX_PROJECT` | 默认项目名称 |\n\n---\n\n## Markdown 渲染组件\n\nPhoenix 前端使用 `streamdownComponents` 实现 Markdown 内容的安全渲染。该组件库基于 `mdast` 和 `hast` 规范，提供自定义的 React 组件映射。\n\n资料来源：[app/src/components/markdown/streamdownComponents.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/markdown/streamdownComponents.tsx)\n\n### 组件映射表\n\n| Markdown 元素 | React 组件 | 样式 |\n|---------------|------------|------|\n| `blockquote` | `
` | `blockquoteCSS` |\n| `inlineCode` | `` | `inlineCodeCSS` |\n| `table` | `MarkdownTable` | 自定义表格组件 |\n| `thead` | `` | `tableSectionHeaderCSS` |\n| `th` | `` | `tableHeaderCellCSS` |\n| `td` | `` | `tableCellCSS` |\n| `img` | `` | `imageCSS` |\n| `hr` | `
` | `hrCSS` |\n\n### 代码块渲染\n\n```typescript\ninlineCode: ({ children, className }) => (\n \n {children}\n \n),\n```\n\n---\n\n## 工具调用展示组件\n\n`DocsToolDetails` 组件负责渲染 AI Agent 工具调用的输入输出信息，包括搜索结果和错误状态。\n\n资料来源：[app/src/components/agent/DocsToolDetails.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/DocsToolDetails.tsx)\n\n### 工具状态渲染\n\n```mermaid\ngraph TD\n A[ToolInvocationPart] --> B{state}\n B -->|input-received| C[显示输入内容]\n B -->|output-available| D[显示输出内容]\n B -->|output-error| E[显示错误信息]\n B -->|其他状态| F[不显示]\n```\n\n### 核心功能\n\n| 功能 | 说明 |\n|------|------|\n| 搜索输入解析 | 解析 `DocsSearchInput` 提取查询字符串 |\n| 页面输入解析 | 解析 `DocsGetPageInput` 提取页面 URL |\n| 输出截断 | `truncateDocsOutput` 函数限制预览长度 |\n\n#### 输出截断函数\n\n```typescript\nexport function truncateDocsOutput(text: string): string {\n if (text.length <= OUTPUT_PREVIEW_LENGTH) {\n return text;\n }\n return text.slice(0, OUTPUT_PREVIEW_LENGTH) + \"…\";\n}\n```\n\n资料来源：[app/src/components/agent/DocsToolDetails.tsx:90-96](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/DocsToolDetails.tsx)\n\n---\n\n## 标注系统组件\n\n### 标注配置列表\n\n`AnnotationConfigList` 组件提供标注配置的选择和管理功能。\n\n资料来源：[app/src/components/trace/AnnotationConfigList.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/trace/AnnotationConfigList.tsx)\n\n### 标注标签组件\n\n在实验运行表格中，标注通过 `AnnotationLabel` 组件展示，支持点击跳转到对应的追踪记录：\n\n```typescript\n {\n if (annotation.trace) {\n navigate(\n `/projects/${annotation.trace.projectId}/traces/${annotation.trace.traceId}`\n );\n }\n }}\n/>\n```\n\n资料来源：[app/src/pages/example/ExampleExperimentRunsTable.tsx:1-50](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/example/ExampleExperimentRunsTable.tsx)\n\n---\n\n## 配置与常量\n\n### 环境变量解析\n\nPhoenix 前端提供 `@arizeai/phoenix-config` 包用于解析环境变量：\n\n资料来源：[js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n| 变量名 | 常量 | 描述 |\n|--------|------|------|\n| `PHOENIX_HOST` | `ENV_PHOENIX_HOST` | 服务器地址 |\n| `PHOENIX_API_KEY` | `ENV_PHOENIX_API_KEY` | API 密钥 |\n| `PHOENIX_COLLECTOR_ENDPOINT` | `ENV_PHOENIX_COLLECTOR_ENDPOINT` | OTel 收集器端点 |\n| `PHOENIX_PORT` | `ENV_PHOENIX_PORT` | HTTP 端口 |\n| `PHOENIX_GRPC_PORT` | `ENV_PHOENIX_GRPC_PORT` | gRPC 端口 |\n| `PHOENIX_PROJECT` | `ENV_PHOENIX_PROJECT` | 默认项目名 |\n\n---\n\n## 组件目录结构\n\n```\napp/src/\n├── App.tsx # 应用入口\n├── Routes.tsx # 路由配置\n├── pages/\n│ ├── TracingRoot.tsx # 追踪根组件\n│ ├── project/\n│ │ ├── ProjectTracesPage.tsx\n│ │ └── OnboardingSteps.tsx\n│ └── example/\n│ └── ExampleExperimentRunsTable.tsx\n├── components/\n│ ├── trace/\n│ │ ├── TraceTree.tsx\n│ │ ├── AnnotationConfigList.tsx\n│ │ └── DocumentItem.tsx\n│ ├── project/\n│ │ ├── TypeScriptProjectGuide.tsx\n│ │ ├── PythonProjectGuide.tsx\n│ │ └── IntegrationIcons.tsx\n│ ├── agent/\n│ │ └── DocsToolDetails.tsx\n│ ├── markdown/\n│ │ └── streamdownComponents.tsx\n│ ├── core/icon/\n│ │ └── Icons.tsx\n│ └── playground/\n│ └── PromptMenu.tsx\n└── store/\n └── tracingStore.tsx # 状态管理\n```\n\n---\n\n## 技术栈总结\n\n| 类别 | 技术选型 |\n|------|----------|\n| 框架 | React 18+ |\n| 语言 | TypeScript |\n| 路由 | React Router v6 |\n| 状态管理 | Zustand |\n| 数据获取 | Apollo Client (GraphQL) |\n| 样式方案 | CSS-in-JS (内联样式) |\n| UI 组件库 | 内部构建 + Adobe Spectrum |\n| Markdown 渲染 | streamdown |\n| 构建工具 | Vite |\n\n---\n\n## 开发指南\n\n### 新增页面\n\n1. 在 `pages/` 目录下创建页面组件\n2. 在 `Routes.tsx` 中注册路由\n3. 添加面包屑导航配置：\n\n```typescript\n}\n handle={{\n crumb: () => \"新页面\",\n }}\n/>\n```\n\n### 新增组件\n\n1. 根据组件类型选择合适的目录\n2. 遵循现有组件的 props 类型定义模式\n3. 使用 `export` 导出以便复用\n\n### 状态管理\n\n在 `tracingStore.tsx` 中添加新的状态切片：\n\n```typescript\nconst useTracingStore = create()((set) => ({\n // 现有状态\n newState: initialValue,\n setNewState: (value) => set({ newState: value }),\n}));\n\n---\n\n\n\n## 部署配置与容器化\n\n### 相关页面\n\n相关主题：[前端组件架构](#page-008), [系统架构设计](#page-002)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [Dockerfile](https://github.com/Arize-ai/phoenix/blob/main/Dockerfile)\n- [docker-compose.yml](https://github.com/Arize-ai/phoenix/blob/main/docker-compose.yml)\n- [helm/Chart.yaml](https://github.com/Arize-ai/phoenix/blob/main/helm/Chart.yaml)\n- [helm/values.yaml](https://github.com/Arize-ai/phoenix/blob/main/helm/values.yaml)\n- [src/phoenix/config.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/config.py)\n
\n\n# 部署配置与容器化\n\nPhoenix 是一个开源的可观测性平台，支持多种部署方式，包括 Docker 容器化部署和 Kubernetes 集群部署。本页面详细介绍 Phoenix 的环境变量配置、Docker 部署方案以及 Helm Chart 部署方式。\n\n## 环境变量配置\n\nPhoenix 使用环境变量进行运行时配置，这些变量贯穿整个应用程序的生命周期。\n\n### 核心配置变量\n\n| 变量名 | 常量定义 | 类型 | 说明 |\n|--------|----------|------|------|\n| `PHOENIX_HOST` | `ENV_PHOENIX_HOST` | 字符串 | Phoenix 服务器主机地址，格式为 `http://localhost:6006` |\n| `PHOENIX_API_KEY` | `ENV_PHOENIX_API_KEY` | 字符串 | 用于 Phoenix 身份验证的 API 密钥 |\n| `PHOENIX_CLIENT_HEADERS` | `ENV_PHOENIX_CLIENT_HEADERS` | JSON | 客户端请求的自定义请求头 |\n| `PHOENIX_COLLECTOR_ENDPOINT` | `ENV_PHOENIX_COLLECTOR_ENDPOINT` | 字符串 | OpenTelemetry 收集器端点 URL |\n| `PHOENIX_PORT` | `ENV_PHOENIX_PORT` | 整数 | Phoenix HTTP 端口 |\n| `PHOENIX_GRPC_PORT` | `ENV_PHOENIX_GRPC_PORT` | 整数 | OpenTelemetry gRPC 端口 |\n| `PHOENIX_PROJECT` | `ENV_PHOENIX_PROJECT` | 字符串 | 项目操作的默认项目名称 |\n\n资料来源：[js/packages/phoenix-config/README.md]()\n\n### 配置读取机制\n\nPhoenix 的配置模块提供了类型化的配置读取辅助函数。这些辅助函数能够：\n\n- 自动从环境变量中读取配置值\n- 提供类型安全的配置访问接口\n- 支持默认值和必需配置项的验证\n\n```typescript\n// TypeScript 客户端配置示例\nimport { register } from \"@arizeai/phoenix-otel\";\n\nregister({\n projectName: \"my-app\",\n url: \"https://app.phoenix.arize.com\",\n apiKey: process.env.PHOENIX_API_KEY,\n});\n```\n\n资料来源：[js/packages/phoenix-otel/README.md]()\n\n## Docker 部署\n\nPhoenix 提供官方 Docker 镜像，支持单机快速部署场景。\n\n### Docker 镜像架构\n\n```mermaid\ngraph TD\n A[phoenix Docker Image] --> B[Python Runtime]\n A --> C[Phoenix Application]\n A --> D[OpenTelemetry Collector]\n B --> C\n C --> E[SQLite/数据库]\n D --> C\n```\n\n### 端口配置\n\nPhoenix 容器使用以下默认端口：\n\n| 端口 | 协议 | 用途 |\n|------|------|------|\n| 6006 | HTTP | Phoenix Web UI |\n| 4317 | gRPC | OpenTelemetry 接收 |\n| 4318 | HTTP | OpenTelemetry 接收 |\n\n### 环境变量配置\n\n在 Docker 环境中，可通过 `-e` 参数或 `.env` 文件传递配置：\n\n```bash\ndocker run -d \\\n -p 6006:6006 \\\n -e PHOENIX_PORT=6006 \\\n -e PHOENIX_GRPC_PORT=4317 \\\n -e PHOENIX_HOST=http://localhost:6006 \\\n arizephoenix/phoenix:latest\n```\n\n## Docker Compose 部署\n\n对于本地开发和多服务协作场景，Phoenix 支持 Docker Compose 编排部署。\n\n### 服务编排架构\n\n```mermaid\ngraph LR\n A[Phoenix Container] --> B[SQLite Volume]\n A --> C[OpenTelemetry Collector]\n D[Application] -->|Traces| C\n C -->|Export| A\n```\n\n### docker-compose.yml 结构\n\n典型配置文件包含以下服务定义：\n\n- **phoenix**：主应用程序服务\n- **collector**：OpenTelemetry 收集器服务\n- **volumes**：持久化存储卷\n\n```yaml\nservices:\n phoenix:\n image: arizephoenix/phoenix:latest\n ports:\n - \"6006:6006\"\n environment:\n - PHOENIX_PORT=6006\n - PHOENIX_GRPC_PORT=4317\n volumes:\n - phoenix-data:/data\n\n collector:\n image: otel/opentelemetry-collector-contemporary\n ports:\n - \"4317:4317\"\n - \"4318:4318\"\n```\n\n## Kubernetes 部署\n\nPhoenix 提供 Helm Chart 用于 Kubernetes 集群部署，支持生产环境的高可用配置。\n\n### Helm Chart 架构\n\n```mermaid\ngraph TD\n A[Phoenix Helm Release] --> B[Deployment]\n A --> C[Service]\n A --> D[ConfigMap]\n A --> E[Ingress]\n B --> F[Pod: phoenix-app]\n F --> G[ConfigMap: 环境变量]\n F --> H[Secret: API密钥]\n```\n\n### Chart 配置\n\nChart.yaml 定义了 Chart 的基本元数据：\n\n| 字段 | 说明 |\n|------|------|\n| `name` | Chart 名称 |\n| `version` | Chart 版本 |\n| `appVersion` | Phoenix 应用版本 |\n| `kubeVersion` | 支持的 Kubernetes 版本范围 |\n\n### values.yaml 配置选项\n\nHelm Chart 通过 values.yaml 提供灵活的部署配置：\n\n```yaml\n# 镜像配置\nimage:\n repository: arizephoenix/phoenix\n tag: latest\n pullPolicy: IfNotPresent\n\n# 副本配置\nreplicaCount: 1\n\n# 服务配置\nservice:\n type: ClusterIP\n port: 6006\n grpcPort: 4317\n\n# 环境变量配置\nenv:\n PHOENIX_HOST: \"\"\n PHOENIX_PORT: \"6006\"\n PHOENIX_GRPC_PORT: \"4317\"\n PHOENIX_PROJECT: \"default\"\n\n# 资源限制\nresources:\n limits:\n cpu: 1000m\n memory: 2Gi\n requests:\n cpu: 100m\n memory: 512Mi\n\n# Ingress 配置\ningress:\n enabled: false\n className: \"\"\n annotations: {}\n hosts:\n - host: phoenix.local\n paths:\n - path: /\n pathType: Prefix\n```\n\n### 部署命令\n\n```bash\n# 添加 Helm 仓库\nhelm repo add arize https://arize-ai.github.io/phoenix\n\n# 安装 Phoenix\nhelm install phoenix arize/phoenix\n\n# 自定义配置部署\nhelm install phoenix arize/phoenix -f custom-values.yaml\n\n# 查看部署状态\nhelm status phoenix\n\n# 升级版本\nhelm upgrade phoenix arize/phoenix --set image.tag=v2.0.0\n```\n\n## Python SDK 配置\n\nPython 应用程序通过 `arize-phoenix-otel` 包与 Phoenix 集成。\n\n### 自动环境变量读取\n\n`arize-phoenix-otel` 包会自动从环境变量中读取配置，无需显式编码：\n\n```python\nimport os\n\n# 设置环境变量\nos.environ[\"PHOENIX_HOST\"] = \"http://localhost:6006\"\nos.environ[\"PHOENIX_API_KEY\"] = \"your-api-key\"\nos.environ[\"PHOENIX_PROJECT\"] = \"my-project\"\n```\n\n### OTEL 初始化代码\n\n```python\nfrom phoenix.otel import register\n\n# 注册 Phoenix 作为 OTEL provider\nprovider = register(project_name=\"my-app\")\n\n# 你的应用代码...\n\n# 关闭时清理资源\nawait provider.shutdown()\n```\n\n资料来源：[app/src/components/project/PythonProjectGuide.tsx]()\n\n## 认证与安全配置\n\n### API Key 配置\n\n当启用认证时，Phoenix 需要 API Key 进行身份验证：\n\n| 配置方式 | 适用场景 | 配置路径 |\n|----------|----------|----------|\n| 个人 API Key | 单用户开发 | `/profile` 页面管理 |\n| 系统 API Key | 服务间通信 | `/settings/general` 页面管理 |\n\n```typescript\n// TypeScript 客户端认证配置\nconst client = new PhoenixClient({\n host: process.env.PHOENIX_HOST,\n apiKey: process.env.PHOENIX_API_KEY,\n headers: {\n \"X-Custom-Header\": \"value\"\n }\n});\n```\n\n### 自定义请求头配置\n\n通过 `PHOENIX_CLIENT_HEADERS` 环境变量设置自定义请求头：\n\n```bash\n# JSON 格式编码的自定义头\nPHOENIX_CLIENT_HEADERS='{\"X-Org-Id\": \"12345\", \"X-Team\": \"ml-team\"}'\n```\n\n资料来源：[js/packages/phoenix-client/README.md]()\n\n## MCP 服务器配置\n\nPhoenix MCP (Model Context Protocol) 服务器支持独立的开发部署。\n\n### 开发环境配置\n\n创建 `.env` 文件配置 MCP 服务器：\n\n```bash\nPHOENIX_API_KEY=your-api-key\nPHOENIX_HOST=https://my-phoenix.com\nPHOENIX_PROJECT=default-project\nPHOENIX_CLIENT_HEADERS={}\n```\n\n### MCP 服务器启动\n\n```json\n{\n \"mcpServers\": {\n \"phoenix\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@arizeai/phoenix-mcp@latest\",\n \"--baseUrl\",\n \"https://my-phoenix.com\",\n \"--apiKey\",\n \"your-api-key\"\n ]\n }\n }\n}\n```\n\n资料来源：[js/packages/phoenix-mcp/README.md]()\n\n## 部署架构总览\n\n```mermaid\ngraph TB\n subgraph \"客户端层\"\n A[Python App
arize-phoenix-otel]\n B[TypeScript App
@arizeai/phoenix-otel]\n C[CLI Agent
phoenix-cli]\n end\n\n subgraph \"网络层\"\n D[Ingress Controller]\n E[Load Balancer]\n end\n\n subgraph \"Kubernetes 集群\"\n F[Phoenix Pod]\n G[OTEL Collector Pod]\n H[PostgreSQL/MySQL]\n end\n\n A -->|OTLP Protocol| G\n B -->|OTLP Protocol| G\n C -->|REST API| F\n G -->|Export| F\n D --> F\n E --> D\n F --> H\n```\n\n## 常见部署场景\n\n### 本地开发环境\n\n```bash\n# 使用 Docker Compose 快速启动\ndocker-compose up -d\n\n# 或使用 pnpm 开发模式\ncd js\npnpm install\npnpm dev\n```\n\n### 生产环境部署\n\n```bash\n# 1. 创建 Kubernetes 命名空间\nkubectl create namespace phoenix\n\n# 2. 创建 Secret 存储 API Key\nkubectl create secret generic phoenix-secrets \\\n --from-literal=PHOENIX_API_KEY=your-key \\\n --namespace phoenix\n\n# 3. 安装 Helm Chart\nhelm install phoenix arize/phoenix \\\n --namespace phoenix \\\n --set ingress.enabled=true \\\n --set ingress.hostname=phoenix.example.com \\\n --set replicaCount=3\n```\n\n### 云端托管部署\n\n对于云端托管的 Phoenix Cloud，使用生产配置：\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\n\nregister({\n projectName: \"production-app\",\n url: \"https://app.phoenix.arize.com\",\n apiKey: process.env.PHOENIX_API_KEY,\n});\n```\n\n## 配置优先级\n\nPhoenix 配置按以下优先级生效（从高到低）：\n\n1. **代码级别配置**：直接在代码中传递的参数\n2. **环境变量**：运行时环境变量\n3. **配置文件**：values.yaml 或 config.py 中的默认值\n4. **编译时默认值**：镜像内置的默认值\n\n## 故障排查\n\n### 常见配置问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 连接被拒绝 | 端口配置不匹配 | 检查 `PHOENIX_PORT` 和容器端口映射 |\n| 认证失败 | API Key 无效 | 验证 `PHOENIX_API_KEY` 配置 |\n| gRPC 连接失败 | 防火墙阻止 | 开放 4317 端口或检查 `PHOENIX_GRPC_PORT` |\n| 配置不生效 | 缓存问题 | 重启 Pod 或清除缓存 |\n\n### 诊断命令\n\n```bash\n# 查看 Phoenix 日志\nkubectl logs -n phoenix deployment/phoenix\n\n# 检查服务健康状态\ncurl http://phoenix-service:6006/health\n\n# 验证环境变量\nkubectl exec -n phoenix deployment/phoenix -- env | grep PHOENIX\n\n---\n\n\n\n## Python SDK 参考\n\n### 相关页面\n\n相关主题：[Tracing 系统实现](#page-004)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/phoenix-client/src/phoenix/client/client.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/client.py)\n- [packages/phoenix-otel/src/phoenix/otel/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-otel/src/phoenix/otel/__init__.py)\n- [packages/phoenix-client/src/phoenix/client/resources/spans/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/spans/__init__.py)\n- [packages/phoenix-client/src/phoenix/client/resources/traces/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/traces/__init__.py)\n- [packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/README.md)\n- [js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n
\n\n# Python SDK 参考\n\nPhoenix Python SDK 是 Arize Phoenix 平台的核心客户端库，提供与 Phoenix REST API 交互的完整接口，支持追踪管理、数据集操作、实验运行和评估反馈等功能。\n\n## 概述\n\nPhoenix Python SDK 主要包含两个核心包：\n\n| 包名 | 功能描述 |\n|------|----------|\n| `arize-phoenix-client` | REST API 客户端，支持同步和异步操作 |\n| `arize-phoenix-otel` | OpenTelemetry 集成，用于自动采集追踪数据 |\n\nSDK 支持以下主要功能：\n\n- **追踪管理**：查询和分析分布式追踪数据\n- **跨度操作**：检索和过滤跨度（Span）信息\n- **数据集管理**：创建、追加和版本化管理数据集\n- **实验跟踪**：运行评估实验并追踪结果\n- **评估注释**：添加人工反馈和自动化评估\n\n资料来源：[packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/README.md)\n\n## 安装\n\n使用 pip 安装 Phoenix Python 客户端：\n\n```bash\npip install arize-phoenix-client\n```\n\n对于需要 OpenTelemetry 集成的场景：\n\n```bash\npip install arize-phoenix-otel\n```\n\n资料来源：[packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/README.md)\n\n## 核心架构\n\n### 架构图\n\n```mermaid\ngraph TD\n A[应用程序] --> B[OpenTelemetry SDK]\n A --> C[Phoenix Client]\n B --> D[OTLP Exporter]\n D --> E[Phoenix Collector]\n C --> E\n E --> F[(Phoenix Database)]\n \n G[追踪数据] --> H[Spans API]\n G --> I[Traces API]\n C --> H\n C --> I\n```\n\n### 组件层次\n\n| 层级 | 组件 | 说明 |\n|------|------|------|\n| 用户层 | Phoenix Client | 直接与 REST API 交互 |\n| 用户层 | Phoenix OTEL | 自动instrumentation |\n| 传输层 | OTLP Exporter | OpenTelemetry 协议导出 |\n| 服务层 | Phoenix Server | 数据接收和存储 |\n\n## 环境变量配置\n\nPhoenix SDK 支持通过环境变量自动配置：\n\n| 环境变量 | 说明 | 默认值 |\n|----------|------|--------|\n| `PHOENIX_BASE_URL` | Phoenix 服务器地址 | `http://localhost:6006` |\n| `PHOENIX_API_KEY` | API 认证密钥 | `undefined` |\n| `PHOENIX_CLIENT_HEADERS` | 自定义请求头（JSON格式） | `{}` |\n| `PHOENIX_COLLECTOR_ENDPOINT` | OTel 收集器端点 | `http://localhost:6006` |\n| `PHOENIX_PORT` | Phoenix HTTP 端口 | `6006` |\n| `PHOENIX_GRPC_PORT` | Phoenix gRPC 端口 | `4317` |\n| `PHOENIX_PROJECT` | 默认项目名称 | `default` |\n\n### 云端配置示例\n\n```bash\n# 本地 Phoenix 服务器\nexport PHOENIX_BASE_URL=\"http://localhost:6006\"\n\n# Phoenix 云端实例\nexport PHOENIX_API_KEY=\"your-api-key\"\nexport PHOENIX_BASE_URL=\"https://app.phoenix.arize.com/s/your-space\"\n\n# 自定义请求头\nexport PHOENIX_CLIENT_HEADERS=\"Authorization=Bearer your-api-key,custom-header=value\"\n```\n\n资料来源：[js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n## 客户端初始化\n\n### 同步客户端\n\n```python\nfrom phoenix.client import Client\n\n# 自动从环境变量读取配置\nclient = Client()\n\n# 显式指定配置\nclient = Client(base_url=\"http://localhost:6006\")\n\n# 云端实例带 API 密钥\nclient = Client(\n base_url=\"https://app.phoenix.arize.com/s/your-space\",\n api_key=\"your-api-key\"\n)\n\n# 自定义认证头\nclient = Client(\n base_url=\"https://your-phoenix-instance.com\",\n headers={\"Authorization\": \"Bearer your-api-key\"}\n)\n```\n\n### 异步客户端\n\n```python\nfrom phoenix.client import AsyncClient\n\n# 异步客户端（支持相同配置选项）\nasync_client = AsyncClient()\nasync_client = AsyncClient(base_url=\"http://localhost:6006\")\nasync_client = AsyncClient(\n base_url=\"https://app.phoenix.arize.com/s/your-space\",\n api_key=\"your-api-key\"\n)\n```\n\n资料来源：[packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/README.md)\n\n## Spans API\n\nSpans API 提供对追踪中跨度的查询和分析能力。\n\n### 主要功能\n\n- 查询跨度数据并支持强大的过滤条件\n- 提取跨度属性用于 RAG 评估工作流\n- 获取特定项目的跨度列表\n\n### 使用示例\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# 获取项目中的跨度列表\nspans = client.spans.list_spans(project_name=\"my-project\")\n\n# 过滤特定类型的跨度\nllm_spans = client.spans.list_spans(\n project_name=\"my-project\",\n span_type=\"llm\"\n)\n\n# 获取跨度详情\nspan = client.spans.get_span(span_id=\"span-123\")\n```\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources/spans/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/spans/__init__.py)\n\n## Traces API\n\nTraces API 用于追踪级别的操作和查询。\n\n### 主要功能\n\n- 列出项目中的追踪\n- 获取追踪详情\n- 过滤和搜索追踪数据\n\n### 使用示例\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# 获取追踪列表\ntraces = client.traces.list_traces(project_name=\"my-project\")\n\n# 按时间范围过滤\nrecent_traces = client.traces.list_traces(\n project_name=\"my-project\",\n start_time=\"2024-01-01T00:00:00Z\",\n end_time=\"2024-01-31T23:59:59Z\"\n)\n```\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources/traces/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/traces/__init__.py)\n\n## Datasets API\n\n### 功能概述\n\n- 从 DataFrame、CSV 文件或字典创建数据集\n- 追加数据到现有数据集\n- 版本化管理数据集\n\n### 使用示例\n\n```python\nfrom phoenix.client import Client\nimport pandas as pd\n\nclient = Client()\n\n# 从 DataFrame 创建数据集\ndf = pd.DataFrame({\n \"input\": [\"What is Phoenix?\", \"How to install?\"],\n \"output\": [\"Phoenix is...\", \"Run pip install...\"]\n})\ndataset = client.datasets.create_dataset(\n name=\"my-dataset\",\n dataframe=df\n)\n\n# 获取数据集\ndataset = client.datasets.get_dataset(\n dataset=\"my-dataset\",\n version_id=\"v1.0.0\" # 可选，指定版本\n)\n\n# 追加数据\nclient.datasets.append_to_dataset(\n dataset_name=\"my-dataset\",\n dataframe=new_df\n)\n```\n\n资料来源：[packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/README.md)\n\n## OpenTelemetry 集成\n\n### 快速开始\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\n\nregister({\n projectName: \"my-app\",\n url: \"https://app.phoenix.arize.com\",\n apiKey: process.env.PHOENIX_API_KEY,\n});\n```\n\n### 配置选项\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `projectName` | `string` | `\"default\"` | 项目名称 |\n| `url` | `string` | `\"http://localhost:6006\"` | Phoenix 实例 URL |\n| `apiKey` | `string` | `undefined` | API 认证密钥 |\n| `headers` | `Record` | `{}` | 自定义请求头 |\n| `batch` | `boolean` | `true` | 使用批量跨度处理 |\n| `instrumentations` | `Instrumentation[]` | `undefined` | OpenTelemetry instrumentations |\n\n### Python 端环境变量配置\n\n```bash\n# 本地 Phoenix 服务器\nexport PHOENIX_COLLECTOR_ENDPOINT=\"http://localhost:6006\"\n\n# Phoenix 云端\nexport PHOENIX_COLLECTOR_ENDPOINT=\"https://app.phoenix.arize.com\"\nexport PHOENIX_API_KEY=\"your-api-key\"\n```\n\n资料来源：[js/packages/phoenix-otel/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-otel/README.md)\n\n## 认证机制\n\n### API Key 认证\n\nPhoenix 支持多种认证方式：\n\n```python\nfrom phoenix.client import Client\n\n# 方式一：环境变量\n# 设置 PHOENIX_API_KEY 环境变量\nclient = Client()\n\n# 方式二：客户端初始化时传入\nclient = Client(\n base_url=\"https://app.phoenix.arize.com/s/your-space\",\n api_key=\"your-api-key\"\n)\n```\n\n### OpenTelemetry SDK 认证\n\n当使用 OpenTelemetry SDK 时，通过环境变量配置认证：\n\n```bash\n# 方式一：环境变量\nexport PHOENIX_API_KEY=\"your-api-key\"\n\n# 方式二：OTEL 头信息\nexport OTEL_EXPORTER_OTLP_HEADERS=\"Authorization=Bearer your-api-key\"\n```\n\n### REST/GraphQL API 认证\n\n```bash\n# Bearer Token 认证\nAuthorization: Bearer your-api-key\n```\n\n资料来源：[app/src/components/auth/OneTimeAPIKeyDialog.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/auth/OneTimeAPIKeyDialog.tsx)\n\n## 数据流架构\n\n```mermaid\nsequenceDiagram\n participant App as 应用程序\n participant OTel as OpenTelemetry SDK\n participant Exporter as OTLP Exporter\n participant Phoenix as Phoenix Server\n participant Client as Phoenix Client\n \n App->>OTel: 业务逻辑执行\n OTel->>OTel: 自动instrumentation\n OTel->>Exporter: 发送Span数据\n Exporter->>Phoenix: HTTP/gRPC传输\n Phoenix->>Phoenix: 存储到数据库\n \n App->>Client: API请求\n Client->>Phoenix: REST API调用\n Phoenix->>Client: 返回数据\n Client->>App: 查询结果\n```\n\n## 最佳实践\n\n### 1. 客户端管理\n\n```python\n# 推荐：使用上下文管理器\nfrom phoenix.client import Client\n\nwith Client() as client:\n spans = client.spans.list_spans(project_name=\"my-project\")\n # 自动处理连接关闭\n\n# 不推荐：手动管理生命周期\nclient = Client()\n# ... 使用 client\n# client.close() # 容易遗漏\n```\n\n### 2. 环境配置\n\n```python\nimport os\n\n# 显式环境变量设置优于硬编码\nbase_url = os.getenv(\"PHOENIX_BASE_URL\", \"http://localhost:6006\")\napi_key = os.getenv(\"PHOENIX_API_KEY\")\n\nclient = Client(\n base_url=base_url,\n api_key=api_key\n)\n```\n\n### 3. 错误处理\n\n```python\nfrom phoenix.client import Client\nfrom phoenix.exceptions import PhoenixError\n\ntry:\n client = Client()\n dataset = client.datasets.get_dataset(dataset=\"my-dataset\")\nexcept PhoenixError as e:\n print(f\"获取数据集失败: {e}\")\n```\n\n### 4. 性能优化\n\n- 生产环境启用批量处理（默认 `batch=true`）\n- 使用异步客户端处理大量请求\n- 合理设置过滤条件减少数据传输\n\n## 类型定义\n\nSDK 提供完整的类型提示支持：\n\n```python\nfrom phoenix.client import Client\nfrom phoenix.client.resources.spans import SpanModel\n\nclient = Client()\n\n# 类型安全的响应\nspans: list[SpanModel] = client.spans.list_spans(project_name=\"my-project\")\n\nfor span in spans:\n print(span.span_id, span.name, span.attributes)\n```\n\n## 相关资源\n\n- **完整 API 文档**：访问 [Phoenix 官方文档](https://arize-ai.github.io/phoenix/)\n- **示例代码**：查看 `examples/` 目录下的 Jupyter Notebook\n- **集成指南**：参考 [Integrations](https://arize.com/docs/phoenix/tracing/integrations-tracing/openai) 了解各框架集成\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Arize-ai/phoenix\n\n摘要：发现 17 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:564072810 | https://github.com/Arize-ai/phoenix | README/documentation is current enough for a first validation pass.\n\n## 2. 运行坑 · 来源证据：arize-phoenix: v15.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.3.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d364a0a28a14428baff5ca692cb00578 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.3.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 运行坑 · 来源证据：arize-phoenix: v15.5.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ad2696a72e314b52b79d157bf261f7bd | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 运行坑 · 来源证据：arize-phoenix: v15.5.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b75368026b414d1bbe31d7d3e90b2731 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 运行坑 · 来源证据：arize-phoenix: v15.6.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.6.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49d41c4c92f24db2b382ebd014f9bd14 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.6.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：arize-phoenix: v15.7.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.7.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_826b7f8e0d2342cabfedab3cabb1a2dc | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.7.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 运行坑 · 来源证据：arize-phoenix: v15.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.9.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0d47708aa40b4b99b3f132751181cf43 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.9.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:564072810 | https://github.com/Arize-ai/phoenix | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:564072810 | https://github.com/Arize-ai/phoenix | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_547816d87273465a88a09397fc2c4ab1 | https://github.com/Arize-ai/phoenix/issues/13241 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：[security] setup deepsec\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[security] setup deepsec\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_153e6ddc8487493e893542da4c348bbe | https://github.com/Arize-ai/phoenix/issues/13275 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：arize-phoenix: v15.10.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.10.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ce89c62b10a43288f4c6394276bc97c | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.10.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：arize-phoenix: v15.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.4.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fea401ed7b774dc7885c245774e87cce | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.4.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：arize-phoenix: v15.8.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.8.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2ecb08e3e7e04b60ac87fab18439546d | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.8.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | release_recency=unknown\n\n\n", "markdown_key": "phoenix", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:564072810", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/Arize-ai/phoenix" }, { "evidence_id": "art_141f599975834bcfbe3734e8a46fc205", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/Arize-ai/phoenix#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "phoenix 说明书", "toc": [ "https://github.com/Arize-ai/phoenix 项目说明书", "目录", "项目介绍与快速开始", "项目概述", "快速开始", "注册追踪配置", "架构概览", "认证与 API 密钥管理", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "30735f2a451b681dd8c72dfd68b4560712594e62", "repo_inspection_error": null, "repo_inspection_files": [ "pyproject.toml", "Dockerfile", "README.md", "docker-compose.yml", "uv.lock", "docs/PROMPT.md", "docs/openapi.json", "docs/phoenix.mdx", "docs/analytics.js", "docs/phoenix/phoenix-cloud.mdx", "docs/phoenix/sdk-api-reference.mdx", "docs/phoenix/self-hosting.mdx", "docs/phoenix/get-started.mdx", "docs/phoenix/integrations.mdx", "docs/phoenix/agent-assisted-setup.mdx", "docs/phoenix/user-guide.mdx", "docs/phoenix/release-notes.mdx", "docs/phoenix/end-to-end-features-notebook.mdx", "docs/phoenix/cookbook.mdx", "docs/phoenix/skill.md", "docs/phoenix/quickstart.mdx", "docs/phoenix/production-guide.mdx", "docs/phoenix/environments.mdx", "docs/phoenix/phoenix-demo.mdx", "docs/phoenix/prompt-engineering/concepts-prompts.mdx", "docs/phoenix/prompt-engineering/how-to-prompts.mdx", "docs/phoenix/prompt-engineering/overview-prompts.mdx", "docs/phoenix/prompt-engineering/tutorial.mdx", "docs/phoenix/cookbook/agent-workflow-patterns.mdx", "docs/phoenix/settings/api-keys.mdx", "docs/phoenix/settings/custom-ai-providers.mdx", "docs/phoenix/settings/secrets.mdx", "docs/phoenix/settings/data-retention.mdx", "docs/phoenix/settings/access-control-rbac.mdx", "docs/phoenix/documentation/jp.mdx", "docs/phoenix/documentation/zh.mdx", "docs/phoenix/tracing/how-to-tracing.mdx", "docs/phoenix/tracing/llm-traces.mdx", "docs/phoenix/tracing/features-tracing.mdx", "docs/phoenix/tracing/tutorial.mdx" ], "repo_inspection_verified": true, "review_reasons": [], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# phoenix-ui - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 phoenix-ui 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.agents/skills/agent-browser/SKILL.md`, `.agents/skills/mintlify/SKILL.md`, `.agents/skills/phoenix-cli/SKILL.md`, `.agents/skills/phoenix-design/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.agents/skills/agent-browser/SKILL.md`, `.agents/skills/mintlify/SKILL.md`, `.agents/skills/phoenix-cli/SKILL.md`, `.agents/skills/phoenix-design/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `js/examples/apps/langchain-quickstart/README.md`, `packages/phoenix-client/README.md`, `packages/phoenix-evals/README.md` 等 Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install arize-phoenix` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0010` supported 0.86\n- `pip install arize-phoenix-client` 证据：`packages/phoenix-client/README.md` Claim：`clm_0006` supported 0.86\n- `pip install 'arize-phoenix-evals>=2.0.0' openai` 证据：`packages/phoenix-evals/README.md` Claim：`clm_0007` supported 0.86\n- `pip install -r requirements.txt` 证据：`packages/phoenix-otel/docs/README.md` Claim：`clm_0008` supported 0.86\n- `pip install -e .. # Install phoenix-otel package in development mode` 证据：`packages/phoenix-otel/docs/README.md` Claim：`clm_0009` supported 0.86\n- `pip install arize-phoenix-otel` 证据：`packages/phoenix-otel/README.md` Claim：`clm_0010` supported 0.86\n- `pip install openinference-instrumentation-openai` 证据：`packages/phoenix-otel/README.md` Claim：`clm_0011` supported 0.86\n- `pip install openinference-instrumentation-langchain # For LangChain` 证据：`packages/phoenix-otel/README.md` Claim：`clm_0012` supported 0.86\n- `pip install openinference-instrumentation-llama-index # For LlamaIndex` 证据：`packages/phoenix-otel/README.md` Claim：`clm_0013` supported 0.86\n- `npx skills add Arize-ai/phoenix --skill phoenix-tracing` 证据：`packages/phoenix-otel/README.md` Claim：`clm_0014` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.agents/skills/agent-browser/SKILL.md`, `.agents/skills/mintlify/SKILL.md`, `.agents/skills/phoenix-cli/SKILL.md`, `.agents/skills/phoenix-design/SKILL.md` 等 Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.agents/skills/agent-browser/SKILL.md`, `.agents/skills/mintlify/SKILL.md`, `.agents/skills/phoenix-cli/SKILL.md`, `.agents/skills/phoenix-design/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `js/examples/apps/langchain-quickstart/README.md`, `packages/phoenix-client/README.md`, `packages/phoenix-evals/README.md` 等 Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0010` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.agents/skills/agent-browser/SKILL.md`, `.agents/skills/mintlify/SKILL.md`, `.agents/skills/phoenix-cli/SKILL.md`, `.agents/skills/phoenix-design/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `js/examples/apps/langchain-quickstart/README.md`, `packages/phoenix-client/README.md`, `packages/phoenix-evals/README.md` 等\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.agents/skills/agent-browser/SKILL.md`, `.agents/skills/mintlify/SKILL.md`, `.agents/skills/phoenix-cli/SKILL.md`, `.agents/skills/phoenix-design/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `js/examples/apps/langchain-quickstart/README.md`, `packages/phoenix-client/README.md`, `packages/phoenix-evals/README.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0016` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `js/examples/apps/langchain-quickstart/README.md`, `packages/phoenix-client/README.md`, `packages/phoenix-evals/README.md` 等 Claim：`clm_0017` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.agents/skills/agent-browser/SKILL.md`, `.agents/skills/mintlify/SKILL.md`, `.agents/skills/phoenix-cli/SKILL.md`, `.agents/skills/phoenix-design/SKILL.md` 等 Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `js/examples/apps/langchain-quickstart/README.md`, `packages/phoenix-client/README.md`, `packages/phoenix-evals/README.md` 等 Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：5137\n- 重要文件覆盖：40/5137\n- 证据索引条目：107\n- 角色 / Skill 条目：29\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 phoenix-ui 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 phoenix-ui 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 phoenix-ui 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 29 个角色 / Skill / 项目文档条目。\n\n- **agent-browser**（skill）：Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to \"open a website\", \"fill out a form\", \"click a button\", \"take a screenshot\", \"scrape data from a page\", \"test this web app\", \"login to a site\", \"automate… 激活提示：当用户任务与“agent-browser”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/agent-browser/SKILL.md`\n- **mintlify**（skill）：Build and maintain documentation sites with Mintlify. Use when 激活提示：当用户任务与“mintlify”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/mintlify/SKILL.md`\n- **phoenix-cli**（skill）：Debug LLM applications using the Phoenix CLI. Fetch traces, analyze errors, structure trace review with open coding and axial coding, inspect datasets, review experiments, query annotation configs, and use the GraphQL API. Use whenever the user is analyzing traces or spans, investigating LLM/agent failures, deciding what to do after instrumenting an app, building failure taxonomies, choosing what evals to write, or… 激活提示：当用户任务与“phoenix-cli”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-cli/SKILL.md`\n- **phoenix-design**（skill）：Design system conventions for the Phoenix frontend — layout, dialogs, error display, BEM CSS class naming, and CSS design tokens. Use when building UI, naming CSS classes, creating or consuming tokens, handling errors, or designing dialog interactions in app/src/. 激活提示：当用户任务与“phoenix-design”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-design/SKILL.md`\n- **phoenix-docs-gap-audit**（skill）： 激活提示：当用户任务与“phoenix-docs-gap-audit”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-docs-gap-audit/SKILL.md`\n- **phoenix-evals-new-metric**（skill）：- 激活提示：当用户任务与“phoenix-evals-new-metric”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-evals-new-metric/SKILL.md`\n- **phoenix-evals**（skill）：Build and run evaluators for AI/LLM applications using Phoenix. 激活提示：当用户任务与“phoenix-evals”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-evals/SKILL.md`\n- **phoenix-frontend**（skill）：Frontend development guidelines for the Phoenix AI observability platform. Use when writing, reviewing, or modifying React components, TypeScript code, styles, or UI features in the app/ directory. Triggers on any frontend task — new components, UI changes, styling, accessibility fixes, form handling, or component refactoring. Also use when the user asks about frontend conventions or component patterns for this proj… 激活提示：当用户任务与“phoenix-frontend”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-frontend/SKILL.md`\n- **phoenix-github**（skill）：Manage GitHub issues, labels, and project boards for the Arize-ai/phoenix repository. Use when filing roadmap issues, triaging bugs, applying labels, managing the Phoenix roadmap project board, or querying issue/project state via the GitHub CLI. 激活提示：当用户任务与“phoenix-github”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-github/SKILL.md`\n- **phoenix-integration-snippets**（skill）： 激活提示：当用户任务与“phoenix-integration-snippets”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-integration-snippets/SKILL.md`\n- **phoenix-llms-txt**（skill）： 激活提示：当用户任务与“phoenix-llms-txt”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-llms-txt/SKILL.md`\n- **phoenix-playwright-tests**（skill）：Write Playwright E2E tests for the Phoenix AI observability platform. Use when creating, updating, or debugging Playwright tests, or when the user asks about testing UI features, writing E2E tests, or automating browser interactions for Phoenix. 激活提示：当用户任务与“phoenix-playwright-tests”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-playwright-tests/SKILL.md`\n- **phoenix-pr-screenshot**（skill）：Screenshot a running Phoenix feature and attach images to a GitHub PR. Builds the frontend, starts Phoenix with env vars, uses agent-browser to capture screenshots, uploads to GCS, and updates the PR body. 激活提示：当用户任务与“phoenix-pr-screenshot”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-pr-screenshot/SKILL.md`\n- **phoenix-pxi-playwright**（skill）：Write, extend, and debug PXI Playwright E2E tests for Phoenix. Use when adding PXI agent frontend specs, authoring LLM-as-judge rubrics, asserting PXI tool use, persisting PXI test runs as Phoenix experiments, or debugging PXI E2E failures. 激活提示：当用户任务与“phoenix-pxi-playwright”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-pxi-playwright/SKILL.md`\n- **phoenix-pxi**（skill）：Development guide for the Phoenix PXI agent. Use when modifying PXI-specific frontend or backend behavior, extending PXI tool wiring, updating PXI runtime capabilities, or changing the PXI agent request/dispatch flow. Start here for PXI-specific workflows, then read the relevant resource file for the layer you are changing. 激活提示：当用户任务与“phoenix-pxi”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-pxi/SKILL.md`\n- **phoenix-release-notes**（skill）： 激活提示：当用户任务与“phoenix-release-notes”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-release-notes/SKILL.md`\n- **phoenix-release-please**（skill）： 激活提示：当用户任务与“phoenix-release-please”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-release-please/SKILL.md`\n- **phoenix-rest-api**（skill）： 激活提示：当用户任务与“phoenix-rest-api”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-rest-api/SKILL.md`\n- **phoenix-server**（skill）： 激活提示：当用户任务与“phoenix-server”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-server/SKILL.md`\n- **phoenix-skills-audit**（skill）： 激活提示：当用户任务与“phoenix-skills-audit”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-skills-audit/SKILL.md`\n- **phoenix-tracing**（skill）：OpenInference semantic conventions and instrumentation for Phoenix AI observability. Use when implementing LLM tracing, creating custom spans, or deploying to production. 激活提示：当用户任务与“phoenix-tracing”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-tracing/SKILL.md`\n- **phoenix-typescript-package-docs**（skill）： 激活提示：当用户任务与“phoenix-typescript-package-docs”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-typescript-package-docs/SKILL.md`\n- **phoenix-typescript**（skill）：TypeScript conventions and patterns for any TypeScript code in the Phoenix monorepo — including js/packages/, app/, and any other TS directories. Use this skill whenever writing, reviewing, or modifying TypeScript code — new functions, types, exports, tests, or refactors. Also trigger when the user asks about TS patterns, naming conventions, or best practices for this project. 激活提示：当用户任务与“phoenix-typescript”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/phoenix-typescript/SKILL.md`\n- **typescript-tooling-migration**（skill）：Migrate or upgrade TypeScript tooling in the Phoenix monorepo. Use when upgrading TypeScript versions, switching tools ESLint to oxlint, Prettier to oxfmt , upgrading bundlers Vite, esbuild , or making major dependency upgrades. Triggers on requests to migrate, upgrade, or replace TypeScript/JavaScript tooling. 激活提示：当用户任务与“typescript-tooling-migration”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/typescript-tooling-migration/SKILL.md`\n- **vercel-react-best-practices**（skill）：React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements. 激活提示：当用户任务与“vercel-react-best-practices”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/vercel-react-best-practices/SKILL.md`\n- **arize-phoenix**（skill）：Open-source AI observability platform for tracing, evaluating, and improving LLM applications with OpenTelemetry integration 激活提示：当用户任务与“arize-phoenix”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`docs/phoenix/skill.md`\n- **phoenix-cli-development**（skill）： 激活提示：当用户任务与“phoenix-cli-development”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`js/packages/phoenix-cli/.agents/skills/phoenix-cli-development/SKILL.md`\n- **phoenix-client-development**（skill）： 激活提示：当用户任务与“phoenix-client-development”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`js/packages/phoenix-client/.agents/skills/phoenix-client-development/SKILL.md`\n- **phoenix-otel-development**（skill）： 激活提示：当用户任务与“phoenix-otel-development”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`js/packages/phoenix-otel/.agents/skills/phoenix-otel-development/SKILL.md`\n\n## 证据索引\n\n- 共索引 107 条证据。\n\n- **Phoenix OTEL Documentation**（documentation）：This directory contains the Sphinx documentation for the arize-phoenix-otel package. 证据：`packages/phoenix-otel/docs/README.md`\n- **Arize Phoenix**（skill_instruction）：Phoenix is an open-source AI observability platform built on OpenTelemetry that helps developers understand, debug, and improve AI applications. It provides comprehensive tracing, evaluation, prompt engineering, and experimentation capabilities for LLM-based systems. Phoenix captures detailed execution information from AI applications, measures output quality with evaluators, enables systematic prompt iteration, and supports data-driven experimentation to optimize AI performance. 证据：`docs/phoenix/skill.md`\n- **Agent Instructions**（documentation）：This repo uses a Makefile for all build, test, lint, and dev commands. Run make help to see all available targets. 证据：`AGENTS.md`\n- **Installation**（documentation）：Phoenix is an open-source AI observability platform designed for experimentation, evaluation, and troubleshooting. It provides: 证据：`README.md`\n- **Maintenance README for Phoenix Sphinx API Documentation**（documentation）：Maintenance README for Phoenix Sphinx API Documentation 证据：`api_reference/README.md`\n- **Arize Phoenix App**（documentation）：The Phoenix application is a web application built to enable rapid troubleshooting and EDA of model inferences and LLM applications. It is hosted by the Phoenix server and consumes the GraphQL API served by the Python runtime. 证据：`app/README.md`\n- **Phoenix Examples**（documentation）：A collection of examples demonstrating how to use Phoenix. 证据：`examples/README.md`\n- **phoenix-helm**（documentation）：! Version: 7.0.9 https://img.shields.io/badge/Version-7.0.9-informational?style=flat-square ! Type: application https://img.shields.io/badge/Type-application-informational?style=flat-square ! AppVersion: 15.9.0 https://img.shields.io/badge/AppVersion-15.9.0-informational?style=flat-square 证据：`helm/README.md`\n- **Internal Documentation**（documentation）：This folder contains materials that are only relevant to core maintainers of this project. 证据：`internal_docs/README.md`\n- **Readme**（documentation）：Official TypeScript libraries for interacting with a running Arize Phoenix https://github.com/Arize-ai/phoenix instance. 证据：`js/README.MD`\n- **Readme**（documentation）：This directory contains a set of manifests and overlays that describe our various Kubernetes deployment options. These deployments can be invoked from the repository root. 证据：`kustomize/README.md`\n- **Phoenix Scripts**（documentation）：Utility, testing, data-generation, and CI scripts that support Phoenix development. Most Python scripts can be run with uv run scripts/ ; some declare PEP 723 inline dependencies and others assume the project venv is active. 证据：`scripts/README.md`\n- **Phoenix Coding Agent Skills**（documentation）：This directory contains skills https://docs.anthropic.com/en/docs/claude-code/skills that teach coding agents how to work with Phoenix. They can be used with Claude Code, Cursor, and other compatible tools. 证据：`.agents/skills/README.md`\n- **Phoenix Tracing Skill**（documentation）：OpenInference semantic conventions and instrumentation guides for Phoenix. 证据：`.agents/skills/phoenix-tracing/README.md`\n- **React Best Practices**（documentation）：Version 1.0.0 Vercel Engineering January 2026 证据：`.agents/skills/vercel-react-best-practices/AGENTS.md`\n- **agent-framework-analysis**（documentation）：This project shows the same agent defined in multiple different frameworks: - Pure Code aka no framework - LangGraph - LlamaIndex Workflows 证据：`examples/agent_framework_comparison/README.md`\n- **Agents**（documentation）：Example agent implementations instrumented with OpenInference https://github.com/Arize-ai/openinference and traced to Phoenix https://github.com/Arize-ai/phoenix . Each example runs benchmark tasks through an agent framework, producing rich traces with LLM calls, tool executions, and multi-turn conversation flows. 证据：`examples/agents/README.md`\n- **tau-bench + LangGraph**（documentation）：A customer service agent built with LangGraph, instrumented with OpenInference, running tau-bench retail domain tasks. This is the LangGraph counterpart to the OpenAI Agents SDK implementation ../tau bench openai agents/README.md — same tools, same database, same simulated user, different framework. Comparing traces between the two reveals how framework choice affects what trajectory information is available. 证据：`examples/agents/tau_bench_langgraph/README.md`\n- **tau-bench + OpenAI Agents SDK**（documentation）：A customer service agent built with the OpenAI Agents SDK, instrumented with OpenInference, running tau-bench retail domain tasks. This is part of the trajectory evaluation investigation — examining what OTel traces capture when an agent framework naturally handles tool-calling conversations. 证据：`examples/agents/tau_bench_openai_agents/README.md`\n- **TRAJECT-Bench + LangGraph**（documentation）：A single-turn tool-calling agent built with LangGraph, instrumented with OpenInference, running TRAJECT-Bench https://huggingface.co/datasets/Jnnamchi/traject-bench tasks. This contrasts with the tau-bench examples on every dimension: single-turn not multi-turn , mock tools not live DB mutations , parallel and sequential tool patterns not conversational . 证据：`examples/agents/traject_bench_langgraph/README.md`\n- **Code Generation Agent Example**（documentation）：This folder contains examples for building a Code Generation Code-Gen agent using the LangChain library. This agent is designed to generate, refine, and validate code using OpenAI models. 证据：`examples/code_gen_agent/README.md`\n- **Computer Use Agent Examples**（documentation）：This repository contains examples for building a Computer Use Operator Agent using LangGraph and Anthropic . The agent leverages Anthropic's beta APIs to perform various computer-related tasks, including executing Bash commands, editing files, and performing system operations. 证据：`examples/computer_use_agent/README.md`\n- **Running Evals with Cron**（documentation）：This example demonstrates how to compute and upload evals on a regular schedule using cron . 证据：`examples/cron-evals/README.md`\n- **Llama Researcher**（documentation）：In this tutorial, we'll create LLama-Researcher using LlamaIndex workflows, inspired by GPT-Researcher. https://github.com/assafelovic/gpt-researcher 证据：`examples/llamaindex-workflows-research-agent/README.md`\n- **Agentic RAG Examples**（documentation）：This folder contains examples for building a Retrieval-Augmented Generation RAG agent using the LangChain library. 证据：`examples/rag_agent/README.md`\n- **Deploying Phoenix with a Reverse Proxy**（documentation）：Deploying Phoenix with a Reverse Proxy 证据：`examples/reverse-proxy/README.md`\n- **LDAP Authentication - Appendices**（documentation）：Detailed technical references for the LDAP Authentication specification ../ldap-authentication.md . 证据：`internal_docs/specs/ldap-authentication/README.md`\n- **PostgreSQL JSON vs JSONB Demo**（documentation）：This project demonstrates the key differences between PostgreSQL's JSON and JSONB data types. The most striking difference is how they handle key ordering: 证据：`internal_docs/vignettes/json-jsonb-demo/README.md`\n- **OTel contextvars + async generators**（documentation）：OTel contextvars + async generators 证据：`internal_docs/vignettes/otel-contextvars-async/README.md`\n- **PostgreSQL with TLS Setup**（documentation）：This vignette demonstrates how to set up PostgreSQL with TLS encryption. 证据：`internal_docs/vignettes/postgresql_tls/README.md`\n- **SQLAlchemy Polymorphic User Example**（documentation）：SQLAlchemy Polymorphic User Example 证据：`internal_docs/vignettes/sqlalchemy/polymorphic_user/README.md`\n- **Changesets**（documentation）：Hello and welcome! This folder has been automatically generated by @changesets/cli , a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it in our repository https://github.com/changesets/changesets 证据：`js/.changeset/README.md`\n- **CLI Agent Starter Kit**（documentation）：This is a TypeScript CLI agent starter kit with AI SDK and Anthropic integration. 证据：`js/examples/apps/cli-agent-starter-kit/AGENTS.md`\n- **CLI Agent Starter Kit**（documentation）：A TypeScript CLI agent with AI SDK, Anthropic Claude, and Phoenix observability. Demonstrates a Phoenix documentation assistant with declarative tool architecture. 证据：`js/examples/apps/cli-agent-starter-kit/README.md`\n- **Agent Evaluation Harness**（documentation）：Automated evaluation framework for the Phoenix Documentation Assistant CLI agent. 证据：`js/examples/apps/cli-agent-starter-kit/evals/README.md`\n- **TypeScript Experiments and Evals with Arize Phoenix**（documentation）：TypeScript Experiments and Evals with Arize Phoenix 证据：`js/examples/apps/demo-document-relevancy-experiment/README.md`\n- **TypeScript Experiments Quickstart**（documentation）：This tutorial demonstrates how to run experiments with Phoenix using TypeScript. It shows how to create datasets, define task functions, use code-based and LLM-as-a-Judge evaluators, and compare different versions of an AI agent. 证据：`js/examples/apps/experiments-quickstart/README.md`\n- **LangChain TypeScript Quickstart**（documentation）：A LangChain TypeScript travel planner agent with Phoenix tracing and optional evaluations. 证据：`js/examples/apps/langchain-quickstart/README.md`\n- **Mastra Agent with Arize Phoenix Tracing**（documentation）：Mastra Agent with Arize Phoenix Tracing 证据：`js/examples/apps/mastra-agent/README.md`\n- **Mastra + Phoenix TypeScript Quickstart**（documentation）：Mastra + Phoenix TypeScript Quickstart 证据：`js/examples/apps/mastra-quickstart/README.md`\n- **Phoenix Experiment Runner**（documentation）：This is an example app that uses the phoenix-client and @clack/prompts to run experiments. 证据：`js/examples/apps/phoenix-experiment-runner/README.md`\n- **Phoenix Tracing Tutorial TypeScript**（documentation）：Phoenix Tracing Tutorial TypeScript 证据：`js/examples/apps/tracing-tutorial/README.md`\n- **JavaScript / Deno Notebook Examples**（documentation）：JavaScript / Deno Notebook Examples 证据：`js/examples/notebooks/README.md`\n- **Installation**（documentation）：A command-line interface for Arize Phoenix https://github.com/Arize-ai/phoenix . Fetch traces, inspect datasets, query experiments, and access prompts directly from your terminal—or pipe them into AI coding agents like Claude Code, Cursor, Codex, and Gemini CLI. 证据：`js/packages/phoenix-cli/README.md`\n- **Installation**（documentation）：This package provides a TypeScript client for the Arize Phoenix https://github.com/Arize-ai/phoenix API. It is still under active development and is subject to change. 证据：`js/packages/phoenix-client/README.md`\n- **Running phoenix-client Examples**（documentation）：To run the TypeScript examples in this directory, you need to have tsx installed globally. tsx allows you to run TypeScript files directly without compiling them first. 证据：`js/packages/phoenix-client/examples/README.md`\n- **Installation**（documentation）：Shared configuration parsing utilities used across @arizeai/phoenix-otel and @arizeai/phoenix-client . Provides typed helpers for reading Phoenix environment variables. 证据：`js/packages/phoenix-config/README.md`\n- **Installation**（documentation）：This package provides a TypeScript evaluation library. It is vendor agnostic and can be used in isolation of any framework or platform. This package is still under active development and is subject to change. 证据：`js/packages/phoenix-evals/README.md`\n- **Running phoenix-evals Examples**（documentation）：To run the TypeScript examples in this directory, you need to have tsx installed globally. tsx allows you to run TypeScript files directly without compiling them first. 证据：`js/packages/phoenix-evals/examples/README.md`\n- **Installation**（documentation）：Phoenix MCP Server is an implementation of the Model Context Protocol for the Arize Phoenix platform. It provides a unified interface to Phoenix's capabilities. 证据：`js/packages/phoenix-mcp/README.md`\n- **Features**（documentation）：A lightweight wrapper around OpenTelemetry for Node.js applications that simplifies sending traces to Arize Phoenix https://github.com/Arize-ai/phoenix . @arizeai/phoenix-otel handles provider registration and OTLP export, then re-exports the full @arizeai/openinference-core helper surface from the same package path so you can register tracing and author manual spans from one import. 证据：`js/packages/phoenix-otel/README.md`\n- **Features**（documentation）：arize-phoenix-client Phoenix Client provides an interface for interacting with the Phoenix platform via its REST API, enabling you to manage datasets, run experiments, analyze traces, and collect feedback programmatically. 证据：`packages/phoenix-client/README.md`\n- **arize-phoenix-evals**（documentation）：Phoenix Evals provides lightweight, composable building blocks for writing and running evaluations on LLM applications, including tools to determine relevance, toxicity, hallucination detection, and much more. 证据：`packages/phoenix-evals/README.md`\n- **Features**（documentation）：Provides a lightweight wrapper around OpenTelemetry primitives with Phoenix-aware defaults. Phoenix OTEL also gives you access to tracing decorators for common GenAI patterns. 证据：`packages/phoenix-otel/README.md`\n- **Analytics**（documentation）：Analytics How to Run 证据：`scripts/analytics/README.md`\n- **Phoenix Development Environment**（documentation）：Complete Docker Compose development environment with Phoenix, PostgreSQL, Grafana, Prometheus, and OIDC authentication using Traefik reverse proxy. 证据：`scripts/docker/devops/README.md`\n- **K8s Test Setup for ROLE ATTRIBUTE PATH**（documentation）：K8s Test Setup for ROLE ATTRIBUTE PATH 证据：`scripts/docker/devops/k8s/README.md`\n- **Phoenix OIDC Debug Server**（documentation）：A fully spec-compliant OpenID Connect 1.0 server implementation for testing and debugging authentication flows. This server is designed for development environments and provides comprehensive logging to help understand the OIDC protocol. 证据：`scripts/docker/devops/oidc-server/README.md`\n- **Phoenix SMTP Development Server**（documentation）：A simple SMTP server for visualizing and debugging emails emitted from Phoenix during development. Not for production use. 证据：`scripts/docker/devops/smtp-server/README.md`\n- **Vite Dev Server - Technical Notes**（documentation）：1. Port Conflict Avoidance Problem: Don't want Vite's 5173 exposed on host conflicts, security Solution: Route everything through Traefik on port 18273 - Vite container: expose: \"5173\" internal only, no ports: mapping - Traefik label: traefik.http.services.vite-dev.loadbalancer.server.port=5173 - Client connects to: http://localhost:18273/phoenix/vite/... 证据：`scripts/docker/devops/vite-dev/README.md`\n- 其余 47 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`packages/phoenix-otel/docs/README.md`, `docs/phoenix/skill.md`, `AGENTS.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`packages/phoenix-otel/docs/README.md`, `docs/phoenix/skill.md`, `AGENTS.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍与快速开始**：importance `high`\n - source_paths: README.md, pyproject.toml, Dockerfile\n- **系统架构设计**：importance `high`\n - source_paths: src/phoenix/server/__init__.py, src/phoenix/db/models.py, app/src/Routes.tsx, schemas/openapi.json, app/schema.graphql\n- **数据库模型与迁移**：importance `high`\n - source_paths: src/phoenix/db/models.py, src/phoenix/db/migrations/versions/cf03bd6bae1d_init.py, src/phoenix/db/engines.py, src/phoenix/db/bulk_inserter.py\n- **Tracing 系统实现**：importance `high`\n - source_paths: src/phoenix/server/api/helpers/annotations.py, src/phoenix/db/insertion/span.py, src/phoenix/server/api/dataloaders/span_by_id.py, packages/phoenix-otel/src/phoenix/otel/otel.py\n- **Evaluation 评估系统**：importance `high`\n - source_paths: packages/phoenix-evals/src/llm/ClassificationEvaluator.ts, packages/phoenix-evals/src/llm/createCorrectnessEvaluator.ts, src/phoenix/server/api/evaluators.py, prompts/classification_evaluator_configs/CORRECTNESS_CLASSIFICATION_EVALUATOR_CONFIG.yaml\n- **Datasets 与 Experiments 数据管理**：importance `high`\n - source_paths: src/phoenix/db/insertion/dataset.py, src/phoenix/server/api/input_types/CreateDatasetInput.py, src/phoenix/server/api/helpers/dataset_helpers.py, packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py\n- **Prompt Playground 与管理**：importance `medium`\n - source_paths: app/src/pages/playground/Playground.tsx, src/phoenix/server/api/helpers/prompts/__init__.py, src/phoenix/server/api/helpers/prompts/conversions/openai.py, packages/phoenix-client/src/phoenix/client/resources/prompts/__init__.py\n- **前端组件架构**：importance `medium`\n - source_paths: app/src/App.tsx, app/src/Routes.tsx, app/src/pages/TracingRoot.tsx, app/src/components/trace/TraceTree.tsx, app/src/store/tracingStore.tsx\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `30735f2a451b681dd8c72dfd68b4560712594e62`\n- inspected_files: `pyproject.toml`, `Dockerfile`, `README.md`, `docker-compose.yml`, `uv.lock`, `docs/PROMPT.md`, `docs/openapi.json`, `docs/phoenix.mdx`, `docs/analytics.js`, `docs/phoenix/phoenix-cloud.mdx`, `docs/phoenix/sdk-api-reference.mdx`, `docs/phoenix/self-hosting.mdx`, `docs/phoenix/get-started.mdx`, `docs/phoenix/integrations.mdx`, `docs/phoenix/agent-assisted-setup.mdx`, `docs/phoenix/user-guide.mdx`, `docs/phoenix/release-notes.mdx`, `docs/phoenix/end-to-end-features-notebook.mdx`, `docs/phoenix/cookbook.mdx`, `docs/phoenix/skill.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:564072810 | https://github.com/Arize-ai/phoenix | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：arize-phoenix: v15.3.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.3.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d364a0a28a14428baff5ca692cb00578 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.3.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：arize-phoenix: v15.5.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ad2696a72e314b52b79d157bf261f7bd | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：arize-phoenix: v15.5.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_b75368026b414d1bbe31d7d3e90b2731 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：arize-phoenix: v15.6.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.6.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_49d41c4c92f24db2b382ebd014f9bd14 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.6.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：arize-phoenix: v15.7.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.7.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_826b7f8e0d2342cabfedab3cabb1a2dc | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.7.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：arize-phoenix: v15.9.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.9.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_0d47708aa40b4b99b3f132751181cf43 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.9.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:564072810 | https://github.com/Arize-ai/phoenix | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:564072810 | https://github.com/Arize-ai/phoenix | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n", "summary": "给宿主 AI 的上下文和工作边界。", "title": "AI Context Pack / 带给我的 AI" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：Arize-ai/phoenix\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 来源证据：arize-phoenix: v15.3.0（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：arize-phoenix: v15.5.0（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：arize-phoenix: v15.5.1（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：arize-phoenix: v15.6.0（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n", "summary": "安装、权限、验证和推荐前风险。", "title": "Boundary & Risk Card / 边界与风险卡" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/Arize-ai/phoenix 项目说明书\n\n生成时间：2026-05-16 08:19:14 UTC\n\n## 目录\n\n- [项目介绍与快速开始](#page-001)\n- [系统架构设计](#page-002)\n- [数据库模型与迁移](#page-003)\n- [Tracing 系统实现](#page-004)\n- [Evaluation 评估系统](#page-005)\n- [Datasets 与 Experiments 数据管理](#page-006)\n- [Prompt Playground 与管理](#page-007)\n- [前端组件架构](#page-008)\n- [部署配置与容器化](#page-009)\n- [Python SDK 参考](#page-010)\n\n\n\n## 项目介绍与快速开始\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-002), [前端组件架构](#page-008)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [OnboardingSteps.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/OnboardingSteps.tsx)\n- [PythonProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n- [TypeScriptProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/TypeScriptProjectGuide.tsx)\n- [phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n- [phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n- [phoenix-mcp/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-mcp/README.md)\n- [api_reference/README.md](https://github.com/Arize-ai/phoenix/blob/main/api_reference/README.md)\n- [DocsToolDetails.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/DocsToolDetails.tsx)\n
\n\n# 项目介绍与快速开始\n\n## 项目概述\n\nPhoenix 是由 Arize AI 开发的一个开源可观测性平台，专注于 LLM（大型语言模型）应用的评估与追踪。该项目提供了一套完整的工具集，帮助开发者监控、调试和优化 AI 应用。\n\n### 核心功能\n\n| 功能模块 | 说明 |\n|---------|------|\n| **追踪系统** | 记录 LLM 应用的全链路执行过程 |\n| **评估框架** | 提供多维度评估指标和自动化评测能力 |\n| ** Playground** | 交互式调试和测试 LLM 提示词 |\n| **数据集管理** | 管理测试数据集和评估基准 |\n| **MCP 服务器** | 支持 Model Context Protocol 的工具集成 |\n\n### 技术栈\n\nPhoenix 采用前后端分离架构，主要由以下部分组成：\n\n- **后端**：Python（基于 FastAPI/Gradio）\n- **前端**：React + TypeScript\n- **数据收集**：OpenTelemetry\n- **评估库**：TypeScript/JavaScript（`phoenix-evals`）\n\n## 快速开始\n\n### Python 环境快速配置\n\n#### 安装依赖\n\n使用 pip 安装 Phoenix OTEL 包：\n\n```bash\npip install arize-phoenix-otel\n```\n\n资料来源：[PythonProjectGuide.tsx:15]()\n\n#### 环境变量配置\n\nPhoenix 支持通过环境变量自动配置。以下是核心环境变量：\n\n| 变量名 | 说明 | 示例值 |\n|--------|------|--------|\n| `PHOENIX_HOST` | Phoenix 服务器地址 | `http://localhost:6006` |\n| `PHOENIX_API_KEY` | API 认证密钥 | `your-api-key` |\n| `PHOENIX_CLIENT_HEADERS` | 自定义请求头（JSON 格式） | `{\"X-Custom\":\"value\"}` |\n| `PHOENIX_COLLECTOR_ENDPOINT` | OTel 收集器地址 | `http://collector:4317` |\n| `PHOENIX_PORT` | HTTP 端口 | `6006` |\n| `PHOENIX_GRPC_PORT` | gRPC 端口 | `4317` |\n| `PHOENIX_PROJECT` | 默认项目名称 | `my-project` |\n\n资料来源：[phoenix-config/README.md:18-26]()\n\n#### Python 集成代码\n\n将以下代码添加到应用**最开头**位置，确保在所有代码执行前初始化追踪：\n\n```python\nfrom phoenix.otel import register\n\n# 注册追踪配置\ntracer_provider = register(project_name=\"your-project-name\")\n```\n\n资料来源：[PythonProjectGuide.tsx:52-54]()\n\n### TypeScript/JavaScript 环境快速配置\n\n#### 安装依赖\n\n```bash\nnpm install @arizeai/phoenix-otel\n```\n\n#### 快速开始代码\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\n\n// 初始化追踪\nregister({ projectName: \"your-project-name\" });\n```\n\n资料来源：[TypeScriptProjectGuide.tsx:14-18]()\n\n### 使用 Phoenix Evals 进行评估\n\n`phoenix-evals` 是一个独立的 TypeScript 评估库，可用于创建自定义分类器：\n\n```typescript\nimport { createClassifier } from \"@arizeai/phoenix-evals/llm\";\nimport { openai } from \"@ai-sdk/openai\";\n\nconst model = openai(\"gpt-4o-mini\");\n\nconst classifier = createClassifier({\n model,\n promptTemplate: `\n 评估任务：判断答案是否包含虚假信息。\n 参考文本：{reference}\n 待评估答案：{answer}\n `\n});\n```\n\n资料来源：[phoenix-evals/README.md:25-37]()\n\n## 架构概览\n\n### 系统组件架构\n\n```mermaid\ngraph TD\n A[AI 应用] -->|OTel 追踪| B[Phoenix Collector]\n B --> C[Phoenix Server]\n C --> D[前端 UI]\n C --> E[API 接口]\n \n F[评估请求] -->|phoenix-evals| E\n G[MCP 客户端] -->|MCP 协议| E\n \n style A fill:#e1f5fe\n style C fill:#fff3e0\n style D fill:#e8f5e8\n```\n\n### 追踪数据流\n\n```mermaid\nsequenceDiagram\n participant App as AI 应用\n participant OTel as OpenTelemetry\n participant Phoenix as Phoenix Server\n participant UI as 前端界面\n \n App->>OTel: 发送追踪数据\n OTel->>Phoenix: 收集并转发 Span 数据\n Phoenix->>UI: 提供实时可视化\n UI->>App: 展示追踪链路\n```\n\n## 认证与 API 密钥管理\n\n当启用认证功能时，Phoenix 提供两种 API 密钥类型：\n\n| 密钥类型 | 管理位置 | 适用场景 |\n|---------|---------|---------|\n| 个人 API 密钥 | 用户 Profile 页面 | 个人开发测试 |\n| 系统 API 密钥 | 系统 Settings 页面 | 生产环境部署 |\n\n资料来源：[PythonProjectGuide.tsx:40-47]()\n\n### 生成 API 密钥\n\n在项目设置页面中，已认证用户可以通过\"生成 API 密钥\"按钮创建新的密钥：\n\n```tsx\n\n```\n\n密钥生成后会自动填充到环境变量配置中。\n\n## MCP 服务器集成\n\nPhoenix 提供 MCP（Model Context Protocol）服务器支持，可通过以下配置集成：\n\n```json\n{\n \"mcpServers\": {\n \"phoenix\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@arizeai/phoenix-mcp@latest\",\n \"--baseUrl\",\n \"https://my-phoenix.com\",\n \"--apiKey\",\n \"your-api-key\"\n ]\n }\n }\n}\n```\n\n资料来源：[phoenix-mcp/README.md:45-57]()\n\n### MCP 工具覆盖范围\n\n| 类别 | 支持的工具 |\n|------|-----------|\n| **提示词管理** | `list-prompts`, `get-prompt`, `get-latest-prompt`, `upsert-prompt` 等 |\n| **项目管理** | 项目创建、查询、更新操作 |\n\n## 文档与资源\n\n| 资源类型 | 链接 |\n|---------|------|\n| 官方文档 | [Phoenix 文档](https://arize-ai.github.io/phoenix/) |\n| API 参考 | `api_reference/` 目录下的 Sphinx 文档 |\n| 源码仓库 | [GitHub 仓库](https://github.com/Arize-ai/phoenix) |\n\n## 下一步\n\n- 配置你的第一个追踪项目\n- 使用 phoenix-evals 创建自定义评估器\n- 通过 MCP 集成扩展工具能力\n- 探索 Playground 进行提示词调试\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[项目介绍与快速开始](#page-001), [数据库模型与迁移](#page-003)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/phoenix/server/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/__init__.py)\n- [src/phoenix/db/models.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/models.py)\n- [app/src/Routes.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/Routes.tsx)\n- [schemas/openapi.json](https://github.com/Arize-ai/phoenix/blob/main/schemas/openapi.json)\n- [app/schema.graphql](https://github.com/Arize-ai/phoenix/blob/main/app/schema.graphql)\n- [js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n- [js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n- [js/packages/phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n\n
\n\n# 系统架构设计\n\n## 概述\n\nPhoenix 是一个开源的可观测性平台，主要用于 LLM 应用的可观测性和评估。该系统采用前后端分离架构，支持分布式追踪、评估和数据分析功能。架构设计围绕以下几个核心目标展开：\n\n- **可观测性**：提供完整的追踪、日志和指标采集能力\n- **评估能力**：支持基于 LLM 的自动化评估框架\n- **多语言支持**：提供 Python、TypeScript/JavaScript 客户端 SDK\n- **可扩展性**：支持通过 MCP (Model Context Protocol) 进行扩展\n\n## 整体架构\n\nPhoenix 系统采用分层架构设计，包含以下主要层次：\n\n```mermaid\ngraph TD\n subgraph 客户端层\n A[Python SDK
arize-phoenix-otel] \n B[TypeScript SDK
@arizeai/phoenix-otel]\n C[Phoenix Client
SDK]\n end\n \n subgraph 服务层\n D[Phoenix Server
HTTP/gRPC]\n E[Phoenix MCP
Model Context Protocol]\n end\n \n subgraph 数据层\n F[(SQLite/PostgreSQL
数据库)]\n G[(矢量数据库
可选)]\n end\n \n subgraph 前端层\n H[React Web App
TypeScript]\n end\n \n A --> D\n B --> D\n C --> D\n D --> F\n D --> G\n H --> D\n```\n\n### 架构组件说明\n\n| 组件层级 | 技术栈 | 说明 |\n|---------|--------|------|\n| 客户端 SDK | Python, TypeScript | OTEL 标准的追踪采集 |\n| 服务端 | Python (FastAPI) | HTTP REST API + gRPC |\n| 数据存储 | SQLite/PostgreSQL | 关系型数据存储 |\n| 前端应用 | React + TypeScript | 用户界面 |\n| 扩展协议 | MCP | 模型上下文协议扩展 |\n\n资料来源：[js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n## 数据模型架构\n\nPhoenix 的数据模型定义在 `src/phoenix/db/models.py` 中，核心实体包括：\n\n### 核心数据实体\n\n| 实体名称 | 用途 | 关键字段 |\n|---------|------|---------|\n| Project | 项目隔离 | id, name, description |\n| Trace | 追踪会话 | trace_id, project_id, start_time |\n| Span | 追踪跨度 | span_id, trace_id, name, start_time, end_time |\n| Annotation | 评估标注 | span_id, name, score, label |\n| Dataset | 数据集管理 | id, name, version |\n| Experiment | 实验记录 | id, dataset_id, project_id |\n\n资料来源：[src/phoenix/db/models.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/models.py)\n\n### 数据模型关系图\n\n```mermaid\nerDiagram\n PROJECT ||--o{ TRACE : contains\n PROJECT ||--o{ EXPERIMENT : contains\n TRACE ||--o{ SPAN : contains\n SPAN ||--o{ ANNOTATION : has\n DATASET ||--o{ EXPERIMENT : used_in\n SPAN }o--|| DATASET : references\n```\n\n## API 架构\n\nPhoenix 提供两套 API 接口体系：REST API 和 GraphQL API。\n\n### REST API (OpenAPI)\n\nREST API 基于 OpenAPI 规范定义，提供标准的 HTTP 接口：\n\n```mermaid\ngraph LR\n A[Client] -->|HTTPS| B[FastAPI Router]\n B --> C[Service Layer]\n C --> D[(Database)]\n```\n\n#### 主要 API 端点\n\n| 端点类别 | 路径前缀 | 功能 |\n|---------|---------|------|\n| 项目管理 | `/v1/projects` | 创建、查询、更新项目 |\n| 追踪 | `/v1/traces` | 追踪数据写入和查询 |\n| 跨度 | `/v1/spans` | 跨度数据管理 |\n| 评估 | `/v1/evaluations` | 评估结果管理 |\n| 数据集 | `/v1/datasets` | 数据集 CRUD 操作 |\n\n资料来源：[schemas/openapi.json](https://github.com/Arize-ai/phoenix/blob/main/schemas/openapi.json)\n\n### GraphQL API\n\nGraphQL API 定义在 `app/schema.graphql`，提供更灵活的查询能力：\n\n```graphql\ntype Project {\n id: ID!\n name: String!\n traces: [Trace!]!\n experiments: [Experiment!]!\n}\n\ntype Trace {\n id: ID!\n projectId: ID!\n spans: [Span!]!\n startTime: DateTime!\n}\n\ntype Span {\n id: ID!\n traceId: ID!\n name: String!\n attributes: JSON!\n annotations: [Annotation!]!\n}\n```\n\n资料来源：[app/schema.graphql](https://github.com/Arize-ai/phoenix/blob/main/app/schema.graphql)\n\n## 前端路由架构\n\nReact 前端应用的路由定义在 `app/src/Routes.tsx`：\n\n```mermaid\ngraph TD\n subgraph 路由结构\n A[/] --> B[Projects]\n A --> C[/projects/:id]\n C --> D[Traces]\n C --> E[Spans]\n C --> F[Experiments]\n C --> G[Evals]\n A --> H[/datasets]\n A --> I[/prompts]\n A --> J[/settings]\n end\n```\n\n### 前端组件分布\n\n| 路由路径 | 组件 | 功能 |\n|---------|------|------|\n| `/` | Projects | 项目列表展示 |\n| `/projects/:projectId` | ProjectDetail | 项目详情视图 |\n| `/projects/:projectId/traces` | TracesView | 追踪数据浏览 |\n| `/projects/:projectId/experiments` | ExperimentsView | 实验管理 |\n| `/datasets` | DatasetsView | 数据集管理 |\n| `/prompts` | PromptsView | Prompt 版本管理 |\n\n## 客户端 SDK 架构\n\n### Python SDK\n\nPython SDK (`arize-phoenix-otel`) 提供 OpenTelemetry 标准的集成能力：\n\n```mermaid\ngraph LR\n A[User Application] --> B[Phoenix OTEL SDK]\n B --> C[OTEL Collector]\n C --> D[Phoenix Server]\n D --> E[(Database)]\n```\n\n#### 环境变量配置\n\n| 变量名 | 说明 | 示例值 |\n|-------|------|--------|\n| `PHOENIX_HOST` | 服务器地址 | `http://localhost:6006` |\n| `PHOENIX_PORT` | HTTP 端口 | `6006` |\n| `PHOENIX_GRPC_PORT` | gRPC 端口 | `4317` |\n| `PHOENIX_API_KEY` | API 认证密钥 | `...` |\n| `PHOENIX_PROJECT` | 默认项目名 | `my-project` |\n\n资料来源：[js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n### TypeScript SDK\n\nTypeScript SDK 提供 Node.js 和浏览器环境支持：\n\n```typescript\n// 核心配置接口\ninterface PhoenixConfig {\n host: string; // 服务器地址\n apiKey?: string; // 认证密钥\n headers?: Record; // 自定义请求头\n}\n```\n\n资料来源：[js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n\n## 评估框架架构\n\nPhoenix Evals 提供基于 LLM 的自动化评估能力：\n\n```mermaid\ngraph TD\n A[评估器配置] --> B[createClassifier]\n B --> C[Prompt 模板]\n C --> D[LLM Provider]\n D --> E[评估结果]\n E --> F[Annotation]\n```\n\n### 评估器创建流程\n\n| 步骤 | 操作 | 说明 |\n|-----|------|------|\n| 1 | 选择 LLM Provider | OpenAI, Anthropic, Azure OpenAI 等 |\n| 2 | 定义 Prompt 模板 | 包含评估标准和输入格式 |\n| 3 | 调用 createClassifier | 创建分类器实例 |\n| 4 | 执行评估 | 传入待评估数据进行评分 |\n| 5 | 生成标注 | 将结果写入 Span Annotation |\n\n资料来源：[js/packages/phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n\n## MCP 扩展架构\n\nPhoenix MCP (Model Context Protocol) 服务器提供工具化扩展能力：\n\n```mermaid\ngraph TD\n A[MCP Client
Claude Desktop] --> B[Phoenix MCP Server]\n B --> C[Phoenix Client SDK]\n C --> D[Phoenix REST API]\n D --> E[(Database)]\n```\n\n### MCP 工具覆盖\n\n| 功能领域 | 工具名称 | 说明 |\n|---------|---------|------|\n| Prompts | list-prompts, get-prompt, upsert-prompt | Prompt 版本管理 |\n| Projects | list-projects, get-project | 项目操作 |\n| Traces | query-traces, get-trace | 追踪查询 |\n| Datasets | list-datasets, get-dataset | 数据集操作 |\n\n资料来源：[js/packages/phoenix-mcp/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-mcp/README.md)\n\n## 服务器初始化流程\n\nPhoenix 服务器的初始化定义在 `src/phoenix/server/__init__.py`：\n\n```python\n# 核心初始化流程\ndef create_app() -> FastAPI:\n # 1. 配置加载\n # 2. 数据库连接初始化\n # 3. 中间件注册\n # 4. 路由注册\n # 5. WebSocket 支持\n # 6. CORS 配置\n```\n\n### 服务器组件初始化顺序\n\n| 顺序 | 组件 | 职责 |\n|-----|------|------|\n| 1 | 配置管理 | 加载环境变量和配置文件 |\n| 2 | 数据库连接 | 建立 SQLAlchemy 会话 |\n| 3 | 认证中间件 | JWT/API Key 验证 |\n| 4 | API 路由 | 注册 REST 和 GraphQL 端点 |\n| 5 | WebSocket 处理 | 实时推送支持 |\n| 6 | 静态文件服务 | 前端资源托管 |\n\n资料来源：[src/phoenix/server/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/__init__.py)\n\n## 部署架构\n\nPhoenix 支持多种部署模式：\n\n```mermaid\ngraph LR\n subgraph 本地开发\n A[开发机器] --> B[Docker Compose]\n end\n \n subgraph 云端部署\n C[云服务器] --> D[Container/K8s]\n end\n \n subgraph 托管服务\n E[Arize Cloud] --> F[托管 Phoenix]\n end\n```\n\n### 部署配置矩阵\n\n| 部署模式 | 数据库 | 适用场景 | 扩展性 |\n|---------|-------|---------|--------|\n| 本地开发 | SQLite | 个人测试 | 单一实例 |\n| 生产部署 | PostgreSQL | 企业使用 | 水平扩展 |\n| 托管服务 | 云数据库 | 快速启动 | 自动扩展 |\n\n## 安全架构\n\n### 认证机制\n\n| 认证方式 | 配置变量 | 说明 |\n|---------|---------|------|\n| API Key | `PHOENIX_API_KEY` | Bearer Token 认证 |\n| 自定义 Header | `PHOENIX_CLIENT_HEADERS` | JSON 格式自定义头 |\n| JWT (可选) | 环境变量配置 | 可选的 JWT 验证 |\n\n### 数据隔离\n\n- **项目级隔离**：数据按 Project 隔离\n- **租户隔离**：支持多租户部署\n- **API Key 权限**：系统级和个人级 API Key\n\n## 技术栈汇总\n\n| 层级 | 技术选型 | 版本要求 |\n|-----|---------|---------|\n| 后端框架 | FastAPI | Python 3.8+ |\n| 数据库 ORM | SQLAlchemy | - |\n| 前端框架 | React 18+ | TypeScript 5+ |\n| 状态管理 | Zustand | - |\n| UI 组件库 | Adobe Spectrum | - |\n| 追踪标准 | OpenTelemetry | - |\n| 协议 | REST, GraphQL, gRPC, MCP | - |\n\n## 扩展性设计\n\n### SDK 扩展点\n\n1. **OTEL 处理器**：支持自定义 Span 处理器\n2. **评估器**：可扩展的 LLM 评估框架\n3. **存储后端**：支持多种数据库适配器\n4. **MCP 工具**：可注册的 MCP 工具扩展\n\n### 前端扩展点\n\n| 扩展类型 | 位置 | 说明 |\n|---------|------|------|\n| 路由注册 | Routes.tsx | 新增页面路由 |\n| 组件覆盖 | 各业务组件 | 自定义展示逻辑 |\n| 样式主题 | CSS Variables | 品牌定制 |\n\n资料来源：[app/src/Routes.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/Routes.tsx)\n\n## 总结\n\nPhoenix 系统采用现代化的微服务风格架构设计，通过前后端分离、SDK 多语言支持、标准化的 OpenTelemetry 集成以及灵活的 MCP 扩展机制，为 LLM 应用提供了完整的可观测性解决方案。架构设计注重开发者体验，支持从本地开发到云端托管的多种部署场景。\n\n---\n\n\n\n## 数据库模型与迁移\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-002), [Datasets 与 Experiments 数据管理](#page-006)\n\n由于提供的上下文（START_OF_CONTEXT）中并未包含 `src/phoenix/db/models.py`、`src/phoenix/db/migrations/versions/cf03bd6bae1d_init.py`、`src/phoenix/db/engines.py` 和 `src/phoenix/db/bulk_inserter.py` 等数据库相关源文件，我无法基于这些文件的实际内容生成准确的技术文档。\n\n提供的上下文中仅包含以下类型的文件：\n\n| 文件类型 | 文件路径示例 |\n|---------|-------------|\n| npm 包 README | `js/packages/phoenix-config/README.md`、`js/packages/phoenix-client/README.md` |\n| React 组件 TSX | `app/src/components/project/PythonProjectGuide.tsx` |\n| 配置文件 | `app/package.json` |\n| API 文档说明 | `api_reference/README.md` |\n\n这些文件主要描述了：\n\n- **phoenix-config**：环境变量配置解析工具\n- **phoenix-client**：Python 和 TypeScript 客户端库的使用方法\n- **phoenix-otel**：OpenTelemetry 集成配置\n- **phoenix-evals**：评估库的使用方式\n- **phoenix-cli**：CLI 命令行工具\n\n要完成\"数据库模型与迁移\"这一主题的技术文档，需要访问以下实际数据库源码文件：\n\n
\n缺失的数据库核心源文件\n\n以下文件未在当前上下文中提供，无法进行准确分析：\n\n- `src/phoenix/db/models.py` — ORM 数据模型定义\n- `src/phoenix/db/migrations/versions/cf03bd6bae1d_init.py` — 数据库初始化迁移\n- `src/phoenix/db/engines.py` — 数据库引擎配置\n- `src/phoenix/db/bulk_inserter.py` — 批量数据插入逻辑\n\n
\n\n请提供上述数据库相关源文件的具体内容，或调整查询范围以匹配上下文中已有的文件类型。\n\n---\n\n\n\n## Tracing 系统实现\n\n### 相关页面\n\n相关主题：[Evaluation 评估系统](#page-005), [Python SDK 参考](#page-010)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/phoenix/server/api/helpers/annotations.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/helpers/annotations.py)\n- [src/phoenix/db/insertion/span.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/span.py)\n- [src/phoenix/server/api/dataloaders/span_by_id.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/dataloaders/span_by_id.py)\n- [packages/phoenix-otel/src/phoenix/otel/otel.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-otel/src/phoenix/otel/otel.py)\n- [js/packages/phoenix-otel/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-otel/README.md)\n- [js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n- [src/phoenix/db/README.md](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/README.md)\n
\n\n# Tracing 系统实现\n\n## 概述\n\nPhoenix 的 Tracing 系统是一个完整的可观测性解决方案，用于捕获、分析和可视化 LLM 应用和代理的运行时行为。该系统基于 OpenTelemetry 标准构建，支持多语言客户端（Python 和 TypeScript），能够追踪从简单的函数调用到复杂的多代理工作流。\n\nTracing 的核心作用是记录分布式系统中的请求链路，将每个操作分解为 span（跨度），并关联到对应的项目（Project）和会话（Session）中。资料来源：[src/phoenix/db/README.md]()\n\n## 核心数据模型\n\n### Trace 与 Span 层级结构\n\nPhoenix 使用分层的数据模型来组织追踪数据：\n\n```mermaid\nerDiagram\n Project ||--o{ Trace : has\n Trace ||--o{ Span : contains\n Trace ||--o{ TraceAnnotation : has\n Span ||--o{ SpanAnnotation : has\n Span ||--o{ DocumentAnnotation : has\n```\n\n| 实体 | 描述 | 关联关系 |\n|------|------|----------|\n| **Project** | 追踪项目的顶级容器，用于组织相关的 Trace 数据 | 包含多个 Trace |\n| **Trace** | 单次请求的完整执行链路记录 | 包含多个 Span |\n| **Span** | 追踪中的单个操作单元，记录函数调用或工具执行 | 属于一个 Trace |\n| **SpanAnnotation** | 对 Span 的评估注释，包含正确性、相关性等评估结果 | 关联到用户和 Span |\n| **DocumentAnnotation** | 文档级别的注释，用于 RAG 场景中的文档评估 | 关联到用户和 Span |\n\n资料来源：[src/phoenix/db/README.md]()\n\n### Span 数据结构\n\nSpan 是追踪系统的基本单元，包含以下关键信息：\n\n- **输入/输出消息**：记录函数调用的参数和返回值\n- **时间戳**：操作的开始和结束时间\n- **Token 使用量**：LLM 调用的 token 消耗统计\n- **延迟信息**：操作的响应时间\n- **元数据**：Prompts、Responses 等详细信息\n\n资料来源：[js/examples/apps/langchain-quickstart/README.md]()\n\n## 架构设计\n\n### 系统组件架构\n\n```mermaid\ngraph TD\n A[Application Code] --> B[Phoenix OTEL SDK]\n B --> C[OTLP Exporter]\n C --> D[Phoenix Server]\n D --> E[(Database)]\n \n F[Phoenix Client] --> D\n G[Phoenix Evals] --> D\n H[Phoenix UI] --> D\n \n D --> F\n D --> G\n D --> H\n```\n\n| 组件 | 职责 | 技术栈 |\n|------|------|--------|\n| **Phoenix OTEL SDK** | 在应用程序中收集追踪数据 | Python/TypeScript |\n| **OTLP Exporter** | 通过 OpenTelemetry 协议导出数据 | OpenTelemetry |\n| **Phoenix Server** | 接收、存储和提供追踪数据 | FastAPI/Python |\n| **Phoenix Client** | 提供 Python API 访问追踪数据 | Python |\n| **Phoenix Evals** | 对 Span 进行自动化评估 | LLM-based |\n\n资料来源：[packages/phoenix-otel/src/phoenix/otel/otel.py]()\n\n### OTEL 注册流程\n\nPhoenix OTEL SDK 的核心是 `register()` 函数，用于初始化追踪：\n\n```mermaid\ngraph LR\n A[register config] --> B[Create TracerProvider]\n B --> C[Setup OTLP Exporter]\n C --> D[Register Phoenix]\n D --> E[Return Provider]\n```\n\n**register() 函数配置参数：**\n\n| 参数 | 类型 | 说明 | 示例 |\n|------|------|------|------|\n| `projectName` | string | 项目名称，用于组织追踪数据 | `\"my-llm-app\"` |\n| `url` | string | Phoenix 服务器地址 | `\"https://app.phoenix.arize.com\"` |\n| `apiKey` | string | API 认证密钥 | `process.env.PHOENIX_API_KEY` |\n| `endpoint` | string | OTLP 收集器端点 | `\"http://localhost:6007/v1/traces\"` |\n\n资料来源：[js/packages/phoenix-otel/README.md]()\n\n## 数据加载与查询\n\n### Span 数据加载器\n\nPhoenix Server 提供了 `SpanByID` 数据加载器用于高效获取 Span 数据：\n\n```python\n# 数据加载器接口\nclient.spans.get_spans_dataframe(\n project_identifier=\"my-llm-app\",\n limit=1000,\n root_spans_only=True, # 仅获取顶级 Span\n start_time=datetime.now() - timedelta(hours=24)\n)\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `project_identifier` | string | 必需 | 项目标识符 |\n| `include_spans` | bool | False | 是否包含完整 Span 详情 |\n| `session_id` | str \\| Sequence[str] | None | 按会话 ID 过滤 |\n| `limit` | int | 100 | 最大返回数量 |\n| `timeout` | int | 60 | 请求超时（秒） |\n\n资料来源：[packages/phoenix-client/README.md]()\n\n### 注解数据查询\n\n```python\n# 获取 Span 注解\nannotations_df = client.spans.get_span_annotations_dataframe(\n spans_dataframe=spans_df,\n project_identifier=\"my-llm-app\",\n include_annotation_names=[\"relevance\", \"accuracy\"],\n exclude_annotation_names=[\"note\"]\n)\n```\n\n资料来源：[packages/phoenix-client/README.md]()\n\n## 追踪帮助函数\n\n### TypeScript 追踪工具\n\nPhoenix OTEL 提供了多个追踪辅助函数，简化函数和链路的instrumentation：\n\n| 函数 | 用途 | 典型场景 |\n|------|------|----------|\n| `traceChain()` | 追踪 LangChain/LangGraph 链 | 追踪 LLM 链执行 |\n| `traceAgent()` | 追踪代理执行 | 追踪 AI Agent |\n| `traceTool()` | 追踪工具调用 | 记录外部工具使用 |\n| `observe()` | 通用观测装饰器 | 追踪任意函数 |\n| `withSpan()` | 手动创建 Span | 细粒度控制 |\n\n资料来源：[js/packages/phoenix-otel/README.md]()\n\n### Python 环境变量配置\n\n| 变量 | 常量名 | 描述 |\n|------|--------|------|\n| `PHOENIX_HOST` | `ENV_PHOENIX_HOST` | Phoenix 服务器地址 |\n| `PHOENIX_API_KEY` | `ENV_PHOENIX_API_KEY` | API 认证密钥 |\n| `PHOENIX_COLLECTOR_ENDPOINT` | `ENV_PHOENIX_COLLECTOR_ENDPOINT` | OTLP 收集器端点 |\n| `PHOENIX_PORT` | `ENV_PHOENIX_PORT` | HTTP 端口 |\n| `PHOENIX_GRPC_PORT` | `ENV_PHOENIX_GRPC_PORT` | gRPC 端口 |\n| `PHOENIX_PROJECT` | `ENV_PHOENIX_PROJECT` | 默认项目名称 |\n\n资料来源：[js/packages/phoenix-config/README.md]()\n\n## 注解系统\n\n### 注解配置\n\nPhoenix 支持为项目配置多种类型的注解：\n\n```mermaid\nerDiagram\n Project ||--o{ ProjectAnnotationConfig : has\n AnnotationConfig ||--o{ ProjectAnnotationConfig : configures\n User ||--o{ SpanAnnotation : creates\n User ||--o{ DocumentAnnotation : creates\n User ||--o{ TraceAnnotation : creates\n```\n\n### 注解数据流\n\n```mermaid\ngraph TD\n A[Evaluation Run] --> B[Fetch Spans]\n B --> C[Run LLM Evaluator]\n C --> D[Create Annotations]\n D --> E[Store in DB]\n E --> F[Display in UI]\n```\n\n### 内置评估器\n\nPhoenix 提供了预构建的正确性评估器：\n\n```typescript\n// 预构建评估器\nconst result = await runnableCorrectness评估(spans, {\n rubric: \"travel_rubric\",\n model: fireworksModel\n});\n```\n\n资料来源：[js/examples/apps/langchain-quickstart/README.md]()\n\n## UI 可视化\n\n### Trace 视图\n\nPhoenix UI 提供了完整的 Trace 可视化功能：\n\n- **LangGraph 追踪**：显示代理的整体执行链路\n- **工具调用详情**：展示 essential_info、budget_basics、local_flavor 等工具的执行\n- **Token 使用统计**：记录每个 LLM 调用的 token 消耗\n- **延迟分析**：显示各操作的响应时间\n- **评估注释**：在 Trace 上直接展示正确性评分\n\n资料来源：[js/examples/apps/langchain-quickstart/README.md]()\n\n### 文档注释\n\n在 RAG 场景中，每个检索到的文档都有独立的注释区域：\n\n```typescript\n\n```\n\n资料来源：[app/src/pages/trace/DocumentItem.tsx]()\n\n## 快速开始\n\n### TypeScript 集成\n\n```typescript\nimport { register, traceChain } from \"@arizeai/phoenix-otel\";\n\nconst provider = register({\n projectName: \"my-app\",\n});\n\nconst answerQuestion = traceChain(\n async (question: string) => `Handled: ${question}`,\n { name: \"answer-question\" }\n);\n\nawait answerQuestion(\"What is Phoenix?\");\nawait provider.shutdown();\n```\n\n### Python OTEL 设置\n\n```bash\npip install arize-phoenix-otel\n```\n\n```python\nimport os\nfrom phoenix.otel import register\n\n# 自动从环境变量读取配置\nos.environ[\"PHOENIX_HOST\"] = \"http://localhost:6006\"\n\nregister(project_name=\"my-project\")\n```\n\n资料来源：[app/src/components/project/PythonProjectGuide.tsx]()\n\n## 相关文档\n\n- [Phoenix OTEL SDK](../js/packages/phoenix-otel/README.md)\n- [Phoenix Client API](../packages/phoenix-client/README.md)\n- [Phoenix Evals](../js/packages/phoenix-evals/README.md)\n- [API 参考文档](../api_reference/README.md)\n\n---\n\n\n\n## Evaluation 评估系统\n\n### 相关页面\n\n相关主题：[Tracing 系统实现](#page-004), [Datasets 与 Experiments 数据管理](#page-006)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [js/packages/phoenix-evals/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n- [js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n- [js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n- [app/src/pages/project/SpansTable.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/SpansTable.tsx)\n- [app/src/components/trace/AnnotationConfigList.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/trace/AnnotationConfigList.tsx)\n- [app/src/pages/example/ExampleExperimentRunsTable.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/example/ExampleExperimentRunsTable.tsx)\n- [app/src/components/agent/ToolPart.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/ToolPart.tsx)\n- [app/src/components/agent/DocsToolDetails.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/DocsToolDetails.tsx)\n
\n\n# Evaluation 评估系统\n\n## 概述\n\nPhoenix 的 Evaluation（评估）系统是一个用于评估 LLM 应用输出质量的核心模块。该系统提供了基于 LLM 的自动评估能力，支持幻觉检测、相关性评分、二分类和多分类等评估任务。\n\n评估系统在架构上分为前后端两部分：\n\n- **前端**：React 组件负责展示评估配置、评估结果和注解标注界面\n- **后端**：Python API 提供评估器的注册、配置和管理功能\n- **客户端库**：`@arizeai/phoenix-evals` TypeScript 包提供独立的评估能力\n\n资料来源：[js/packages/phoenix-evals/README.md:1-30](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n\n## 核心架构\n\n### 系统组件关系图\n\n```mermaid\ngraph TD\n A[用户应用] --> B[Phoenix Client]\n B --> C[Traces 数据]\n C --> D[Span Annotations]\n C --> E[Trace Annotations]\n D --> F[Retrieval Metrics]\n F --> G[评估结果展示]\n E --> G\n H[评估配置] --> I[AnnotationConfigList]\n I --> J[AnnotationSummaryGroupTokens]\n G --> J\n```\n\n### 评估类型分类\n\n评估系统支持多种评估类型，主要分为：\n\n| 评估类型 | 说明 | 支持指标 |\n|---------|------|---------|\n| **分类评估** | 二分类或多分类任务 | 准确率、精确率、召回率 |\n| **检索评估** | RAG 检索质量评估 | NDCG、Precision、Hit |\n| **正确性评估** | 答案正确性判断 | 正确/错误 |\n| **幻觉检测** | 检测生成内容中的虚假信息 | 存在/不存在幻觉 |\n\n资料来源：[app/src/pages/project/SpansTable.tsx:180-210](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/SpansTable.tsx)\n\n## 评估器实现\n\n### 创建分类评估器\n\n`@arizeai/phoenix-evals` 包提供了 `createClassifier` 函数，用于创建自定义评估器：\n\n```typescript\nimport { createClassifier } from \"@arizeai/phoenix-evals/llm\";\nimport { openai } from \"@ai-sdk/openai\";\n\nconst model = openai(\"gpt-4o-mini\");\n\nconst classifier = createClassifier({\n model,\n evaluatorName: \"hallucination-detector\",\n promptTemplate: `\n In this task, you will be presented with a query, a reference text and an answer. \n The answer is generated to the question based on the reference text. \n The answer may contain false information. You must use the reference text \n to determine if the answer to the question contains false information.\n `,\n});\n```\n\n资料来源：[js/packages/phoenix-evals/README.md:25-45](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-evals/README.md)\n\n### 评估器工作流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户应用\n participant C as Classifier\n participant M as LLM Model\n participant P as Phoenix Server\n \n U->>C: 传入 Input + Reference\n C->>M: 发送评估 Prompt\n M-->>C: 返回评估结果\n C-->>U: 返回分类标签\n U->>P: 上报评估结果作为 Annotation\n P-->>U: 存储并返回更新\n```\n\n## 评估注解系统\n\n### 注解配置管理\n\n评估注解通过 `AnnotationConfigList` 组件进行管理：\n\n```typescript\n// 注解配置列表数据结构\n{\n id: string,\n name: string,\n annotationType: \"human\" | \"llm\" | \"api\"\n}\n```\n\n资料来源：[app/src/components/trace/AnnotationConfigList.tsx:1-50](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/trace/AnnotationConfigList.tsx)\n\n### 注解显示组件\n\n评估结果通过以下组件层级展示：\n\n| 组件 | 用途 |\n|-----|------|\n| `AnnotationSummaryGroupTokens` | 显示 span 层级的注解摘要 |\n| `TraceAnnotationSummaryGroupTokens` | 显示 trace 层级的注解摘要 |\n| `AnnotationLabel` | 单个注解标签展示 |\n| `RetrievalEvaluationLabel` | 检索评估指标标签 |\n\n资料来源：[app/src/pages/project/SpansTable.tsx:150-230](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/SpansTable.tsx)\n\n### 检索评估指标\n\n检索评估支持以下三个标准指标：\n\n| 指标名 | 说明 | 数据类型 |\n|-------|------|---------|\n| `ndcg` | 归一化折扣累计增益 | float |\n| `precision` | 精确率 | float |\n| `hit` | 命中标记 | boolean |\n\n```typescript\n{row.original.documentRetrievalMetrics.map((retrievalMetric) => {\n return (\n <>\n \n \n \n \n );\n})}\n```\n\n资料来源：[app/src/pages/project/SpansTable.tsx:190-215](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/SpansTable.tsx)\n\n## 实验运行评估\n\n### 评估追踪\n\n评估结果与实验运行关联，支持在 `ExampleExperimentRunsTable` 中查看评估追踪：\n\n```typescript\n// 评估追踪数据结构\n{\n annotation: {\n name: string,\n label: string,\n score?: number,\n trace?: {\n projectId: string,\n traceId: string\n }\n }\n}\n```\n\n点击评估标签可导航到对应的 trace 详情页面：\n\n```typescript\nonClick={() => {\n if (annotation.trace) {\n navigate(\n `/projects/${annotation.trace.projectId}/traces/${annotation.trace.traceId}`\n );\n }\n}}\n```\n\n资料来源：[app/src/pages/example/ExampleExperimentRunsTable.tsx:1-80](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/example/ExampleExperimentRunsTable.tsx)\n\n## 工具输出评估\n\n### 工具调用状态\n\n评估系统也用于标注工具调用的输出状态：\n\n| 状态 | 说明 |\n|-----|------|\n| `input-available` | 输入已提供 |\n| `output-available` | 输出已生成 |\n| `output-error` | 执行出错 |\n\n```typescript\n{part.state === \"output-available\" ? (\n <>\n Output\n {outputStr}\n \n) : null}\n{part.state === \"output-error\" ? (\n <>\n Error\n {part.errorText ?? \"\"}\n \n) : null}\n```\n\n资料来源：[app/src/components/agent/ToolPart.tsx:1-60](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/ToolPart.tsx)\n\n### 文档工具评估\n\n文档搜索工具支持特殊的输出格式评估：\n\n```typescript\nexport function truncateDocsOutput(text: string): string {\n if (text.length <= OUTPUT_PREVIEW_LENGTH) {\n return text;\n }\n return text.slice(0, OUTPUT_PREVIEW_LENGTH) + \"…\";\n}\n```\n\n资料来源：[app/src/components/agent/DocsToolDetails.tsx:1-60](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/DocsToolDetails.tsx)\n\n## 环境配置\n\n### Phoenix 配置变量\n\n评估系统依赖以下环境变量进行配置：\n\n| 变量名 | 用途 | 示例值 |\n|-------|------|--------|\n| `PHOENIX_HOST` | Phoenix 服务地址 | `http://localhost:6006` |\n| `PHOENIX_API_KEY` | API 认证密钥 | `...` |\n| `PHOENIX_PROJECT` | 默认项目名称 | `my-project` |\n| `PHOENIX_COLLECTOR_ENDPOINT` | OTEL 收集器地址 | `http://localhost:4317` |\n\n资料来源：[js/packages/phoenix-config/README.md:20-35](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n### 客户端配置\n\n使用 Phoenix 客户端连接评估服务：\n\n```bash\n# 安装客户端\nnpm install @arizeai/phoenix-client\n\n# 配置连接\nPHOENIX_HOST='http://localhost:12345' \nPHOENIX_API_KEY='xxxxxx' \npnpx tsx examples/list_datasets.ts\n```\n\n```typescript\nimport { Client } from \"@arizeai/phoenix-client\";\n\nconst client = new Client();\n// 自动从环境变量读取配置\n```\n\n资料来源：[js/packages/phoenix-client/README.md:1-40](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n\n## 安装依赖\n\n### Python 环境\n\n```bash\npip install arize-phoenix-otel\npip install arize-phoenix-client\n```\n\n### JavaScript/TypeScript 环境\n\n```bash\nnpm install @arizeai/phoenix-evals\nnpm install @arizeai/phoenix-client\nnpm install @arizeai/phoenix-config\n```\n\n资料来源：[app/src/components/project/PythonProjectGuide.tsx:1-30](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n\n## 数据流总览\n\n```mermaid\nflowchart LR\n subgraph 应用层\n A[用户应用] --> B[Phoenix OTEL]\n A --> C[Phoenix Client]\n end\n \n subgraph 评估层\n B --> D[Traces]\n C --> E[Datasets]\n D --> F[Spans]\n F --> G[Span Annotations]\n G --> H[Retrieval Metrics]\n E --> I[Evaluations]\n end\n \n subgraph 展示层\n G --> J[AnnotationSummary]\n H --> J\n I --> K[Experiment Runs]\n K --> L[Evaluation Labels]\n end\n```\n\n## 最佳实践\n\n### 评估配置建议\n\n1. **使用 LLM 评估器**：利用 `createClassifier` 创建领域特定的评估器\n2. **配置检索指标**：为 RAG 应用配置 NDCG、Precision 和 Hit 指标\n3. **关联 Trace**：确保评估结果与对应的 trace 正确关联\n4. **设置阈值**：根据业务需求设置评估分数阈值\n\n### 性能优化\n\n- 批量处理评估请求减少 API 调用\n- 使用流式处理处理大型文档评估\n- 缓存常用的评估 Prompt 模板\n\n---\n\n\n\n## Datasets 与 Experiments 数据管理\n\n### 相关页面\n\n相关主题：[Evaluation 评估系统](#page-005), [Prompt Playground 与管理](#page-007)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/phoenix/db/insertion/dataset.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/db/insertion/dataset.py)\n- [src/phoenix/server/api/input_types/CreateDatasetInput.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/input_types/CreateDatasetInput.py)\n- [src/phoenix/server/api/helpers/dataset_helpers.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/helpers/dataset_helpers.py)\n- [packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py)\n- [js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n- [app/src/components/experiment/RunExperimentCodeDialog.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/experiment/RunExperimentCodeDialog.tsx)\n
\n\n# Datasets 与 Experiments 数据管理\n\n## 概述\n\nPhoenix 的 Datasets 与 Experiments 模块构成了一个完整的数据管理和实验执行框架。该系统允许用户创建数据集（Dataset）来存储示例数据，并通过实验（Experiment）对数据集进行任务执行和评估。\n\n**核心功能：**\n\n- **数据集管理**：创建、读取、更新、删除数据集\n- **示例管理**：为数据集添加输入（input）、输出（output）和元数据（metadata）\n- **实验执行**：基于数据集运行任务并收集结果\n- **评估系统**：通过评估器（Evaluator）对实验结果进行评分\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py:1-50]()\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n A[Phoenix Client] --> B[REST API]\n B --> C[Dataset Service]\n C --> D[(PostgreSQL Database)]\n \n E[Experiments API] --> C\n F[Experiment Runners] --> E\n \n G[Evaluators] --> E\n \n D --> H[Traces & Spans]\n D --> I[Annotations]\n```\n\n### 数据流架构\n\n```mermaid\ngraph LR\n A[Create Dataset] --> B[Add Examples]\n B --> C[Run Experiment]\n C --> D[Define Task]\n D --> E[Apply Evaluators]\n E --> F[Collect Results]\n F --> G[View Annotations]\n```\n\n资料来源：[js/packages/phoenix-client/README.md:1-80]()\n\n## 数据集（Dataset）模型\n\n### 数据结构\n\n每个 Dataset 包含以下核心字段：\n\n| 字段名 | 类型 | 描述 | 必需 |\n|--------|------|------|------|\n| `name` | string | 数据集名称 | 是 |\n| `description` | string | 数据集描述 | 否 |\n| `examples` | Example[] | 示例数组 | 是 |\n| `version_id` | string | 数据集版本ID | 否 |\n| `metadata` | dict | 附加元数据 | 否 |\n\n### 示例（Example）结构\n\n| 字段名 | 类型 | 描述 | 必需 |\n|--------|------|------|------|\n| `input` | dict | 输入数据，键值对形式 | 是 |\n| `output` | dict | 预期输出数据 | 是 |\n| `metadata` | dict | 示例级元数据 | 否 |\n| `split` | string | 数据集划分（train/test/eval） | 否 |\n\n资料来源：[src/phoenix/server/api/input_types/CreateDatasetInput.py:1-30]()\n\n### Python SDK 数据模型\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# 创建数据集示例\ndataset = client.datasets.create(\n name=\"my-dataset\",\n description=\"数据集描述\",\n examples=[\n {\n \"input\": {\"question\": \"What is the capital of France?\"},\n \"output\": {\"answer\": \"Paris\"},\n \"metadata\": {\"difficulty\": \"easy\"}\n }\n ]\n)\n```\n\n资料来源：[packages/phoenix-client/README.md:40-70]()\n\n## 数据集操作 API\n\n### 创建数据集\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# 基础创建\ndataset = client.datasets.create(\n name=\"questions\",\n description=\"问题数据集\",\n examples=[\n {\n \"input\": {\"question\": \"What is the capital of France\"},\n \"output\": {\"answer\": \"Paris\"},\n \"metadata\": {}\n }\n ]\n)\n\n# 获取返回的 dataset_id\ndataset_id = dataset[\"id\"]\n```\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py:50-80]()\n\n### 获取数据集\n\n```python\n# 通过 ID 获取\ndataset = client.datasets.get_dataset(\n dataset=\"dataset-id-string\",\n version_id=\"optional-version-id\" # 可选，指定版本\n)\n\n# 列出所有数据集\ndatasets = client.datasets.list_datasets()\n```\n\n### 更新数据集\n\n```python\n# 添加新示例\nupdated_dataset = client.datasets.upsert_dataset(\n dataset=\"dataset-id-or-name\",\n examples=[\n {\n \"input\": {\"question\": \"What is the capital of the USA\"},\n \"output\": {\"answer\": \"Washington D.C.\"},\n \"metadata\": {}\n }\n ]\n)\n```\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py:100-150]()\n\n### 插入参数说明\n\n| 参数名 | 类型 | 描述 |\n|--------|------|------|\n| `dataset` | str \\| Dataset object | 数据集标识符或对象 |\n| `examples` | List[dict] | 要添加的示例列表 |\n| `input_keys` | List[str] | 用作输入键的列名 |\n| `output_keys` | List[str] | 用作输出键的列名 |\n| `metadata_keys` | List[str] | 用作元数据键的列名 |\n| `split_key` | str \\| None | 用于划分示例的列名 |\n| `timeout` | int \\| None | 请求超时时间（秒） |\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources/datasets/__init__.py:80-120]()\n\n## 实验（Experiment）系统\n\n### 实验工作流\n\n```mermaid\ngraph TD\n A[创建或获取 Dataset] --> B[定义 Task 函数]\n B --> C[定义 Evaluators]\n C --> D[执行 runExperiment]\n D --> E[收集结果]\n E --> F[查看 Annotations]\n \n G[Task Function] --> H[对每个 Example 执行]\n H --> I[返回实际输出]\n \n J[Evaluators] --> K[评估输出质量]\n K --> L[生成分数/标签]\n```\n\n资料来源：[js/packages/phoenix-client/README.md:80-150]()\n\n### TypeScript 实验执行示例\n\n```typescript\nimport { createDataset } from \"@arizeai/phoenix-client/datasets\";\nimport { asExperimentEvaluator, runExperiment } from \"@arizeai/phoenix-client/experiments\";\n\n// 1. 创建数据集\nconst { datasetId } = await createDataset({\n name: \"names-dataset\",\n description: \"名字数据集\",\n examples: [\n {\n input: { name: \"John\" },\n output: { text: \"Hello, John!\" },\n metadata: {}\n }\n ]\n});\n\n// 2. 定义任务函数\nconst task = async (example) => `hello ${example.input.name}`;\n\n// 3. 定义评估器\nconst evaluators = [\n asExperimentEvaluator({\n name: \"matches\",\n kind: \"CODE\",\n evaluate: async ({ output, expected }) => {\n return { correct: output === expected };\n }\n })\n];\n\n// 4. 运行实验\nconst results = await runExperiment({\n datasetId,\n task,\n evaluators,\n experimentName: \"my-first-experiment\"\n});\n```\n\n资料来源：[js/packages/phoenix-client/README.md:100-160]()\n\n### Python 实验执行\n\n```python\nfrom phoenix.client import Client\nfrom phoenix.experiments import run_experiment\n\nclient = Client()\n\n# 运行实验\nresults = run_experiment(\n experiment_name=\"evaluation-run\",\n dataset_name=\"my-dataset\",\n task=my_task_function,\n evaluators=[accuracy_evaluator, relevance_evaluator]\n)\n\n# 查看结果\nprint(results.metrics)\nprint(results.traces)\n```\n\n## 评估器（Evaluator）系统\n\n### 评估器类型\n\n| 类型 | 描述 | 使用场景 |\n|------|------|----------|\n| `CODE` | 代码执行的确定性评估 | 精确匹配、包含检查 |\n| `LLM` | 基于大语言模型的评估 | 开放性问答、内容质量 |\n| `HUMAN` | 人工标注评估 | 主观判断、敏感内容 |\n\n### 内置评估器\n\nPhoenix 提供了预构建的评估器，包括：\n\n- **准确性评估器**：检查输出是否正确\n- **相关性评估器**：评估与输入的相关程度\n- **文档相关性分类**：判断文档是否回答了问题\n\n资料来源：[src/phoenix/__generated__/classification_evaluator_configs/_document_relevance_classification_evaluator_config.py:1-40]()\n\n### 自定义评估器\n\n```python\nfrom phoenix.experiments import Evaluator\n\nmy_evaluator = Evaluator(\n name=\"custom_eval\",\n evaluate_fn=async def evaluate(example, output):\n # 自定义评估逻辑\n score = calculate_score(output)\n return {\"score\": score, \"label\": \"good\" if score > 0.8 else \"poor\"}\n)\n```\n\n## API 端点参考\n\n### REST API\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/v1/datasets` | POST | 创建数据集 |\n| `/v1/datasets/{id}` | GET | 获取数据集详情 |\n| `/v1/datasets` | GET | 列出所有数据集 |\n| `/v1/datasets/{id}/examples` | POST | 添加示例 |\n| `/v1/experiments` | POST | 运行实验 |\n\n### 获取 Span 数据\n\n```python\nfrom phoenix.client import Client\nfrom datetime import datetime, timedelta\n\nclient = Client()\n\n# 获取 spans 作为 DataFrame\nspans_df = client.spans.get_spans_dataframe(\n project_identifier=\"my-llm-app\",\n limit=1000,\n root_spans_only=True,\n start_time=datetime.now() - timedelta(hours=24)\n)\n\n# 获取 span 标注\nannotations_df = client.spans.get_span_annotations_dataframe(\n spans_dataframe=spans_df,\n project_identifier=\"my-llm-app\",\n include_annotation_names=[\"relevance\", \"accuracy\"]\n)\n```\n\n资料来源：[packages/phoenix-client/README.md:150-200]()\n\n## 认证与授权\n\n### API Key 配置\n\n当启用认证时，需要配置 API Key：\n\n```python\n# 环境变量方式\nimport os\nos.environ[\"PHOENIX_API_KEY\"] = \"your-api-key\"\n\n# 或初始化时指定\nclient = Client(\n api_key=\"your-api-key\",\n endpoint=\"http://localhost:6006\"\n)\n```\n\n### OTEL SDK 认证\n\n```bash\n# 使用 Bearer Token\nOTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer your-api-key'\n```\n\n资料来源：[app/src/components/auth/OneTimeAPIKeyDialog.tsx:50-80]()\n\n## 最佳实践\n\n### 数据集设计\n\n1. **清晰的输入输出结构**：使用一致的 JSON 结构\n2. **充分的元数据**：添加有助于分析的元数据\n3. **版本控制**：使用版本ID追踪数据集变更\n4. **合理划分**：使用 split_key 进行 train/test/eval 划分\n\n### 实验设计\n\n1. **单一职责任务**：每个任务函数只做一件事\n2. **可组合评估器**：将复杂评估拆分为多个评估器\n3. **结果追踪**：使用 experiment_name 命名便于追踪\n4. **批量处理**：利用异步执行提高效率\n\n### 代码生成示例\n\nPhoenix 提供交互式代码生成功能，帮助用户快速上手：\n\n```python\n# 在 UI 中选择数据集后自动生成的代码\nimport arize_phoenix as phoenix\n\nclient = phoenix.Client()\n\n# 获取数据集\ndataset = client.datasets.get_dataset(\n dataset=\"my-dataset-name\",\n version_id=\"optional-version-id\"\n)\n\n# 数据集现已可用于实验\n```\n\n资料来源：[app/src/components/experiment/RunExperimentCodeDialog.tsx:1-50]()\n\n## 总结\n\nPhoenix 的 Datasets 与 Experiments 系统为 LLM 应用评估提供了完整的数据管理和实验执行能力。通过标准化的数据集结构、灵活的评估器系统和丰富的客户端支持，开发者可以高效地进行模型评估和迭代优化。\n\n该系统支持：\n\n- **多语言客户端**：Python、TypeScript/JavaScript\n- **丰富的评估方法**：代码评估、LLM 评估、人工评估\n- **完整的实验追踪**：记录每次运行的结果和标注\n- **灵活的部署选项**：本地部署或云端服务\n\n---\n\n\n\n## Prompt Playground 与管理\n\n### 相关页面\n\n相关主题：[Datasets 与 Experiments 数据管理](#page-006), [数据库模型与迁移](#page-003)\n\n# Prompt Playground 与管理\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [app/src/pages/playground/Playground.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/playground/Playground.tsx)\n- [src/phoenix/server/api/helpers/prompts/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/helpers/prompts/__init__.py)\n- [src/phoenix/server/api/helpers/prompts/conversions/openai.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/server/api/helpers/prompts/conversions/openai.py)\n- [packages/phoenix-client/src/phoenix/client/resources/prompts/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/prompts/__init__.py)\n- [js/packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-client/README.md)\n
\n\n## 概述\n\nPhoenix 的 Prompt Playground 是一个交互式环境，用于测试、调试和管理 LLM（大型语言模型）提示词。该功能允许开发者：\n\n- 实时编辑和测试提示词\n- 查看模型响应\n- 管理多个提示词版本\n- 与 Phoenix 的追踪和评估系统集成\n\n## 核心架构\n\n```mermaid\ngraph TD\n A[Prompt Playground UI] --> B[Phoenix Client SDK]\n B --> C[Phoenix API]\n C --> D[Prompt 管理服务]\n D --> E[OpenAI 兼容转换层]\n E --> F[后端 LLM 提供商]\n \n G[追踪系统] --> C\n H[评估系统] --> C\n```\n\n## 提示词管理 API\n\nPhoenix 提供了 Python 和 TypeScript 两种 SDK 方式来管理提示词。\n\n### Python SDK\n\n```python\nimportarize-phoenix-client\n\nclient = Client()\nprompts = client.prompts\n```\n\n### TypeScript SDK\n\n```typescript\nimport { Client } from \"@arizeai/phoenix-client\";\n\nconst client = new Client({\n host: process.env.PHOENIX_HOST,\n apiKey: process.env.PHOENIX_API_KEY,\n});\n```\n\n## 环境配置\n\nPhoenix Client 支持以下环境变量进行配置：\n\n| 变量名 | 说明 |\n|--------|------|\n| `PHOENIX_HOST` | Phoenix 服务器地址 |\n| `PHOENIX_API_KEY` | API 认证密钥 |\n| `PHOENIX_CLIENT_HEADERS` | 自定义请求头（JSON 格式） |\n\n## 与 OpenTelemetry 集成\n\nPrompt Playground 与 Phoenix 的追踪系统紧密集成。通过配置 OpenTelemetry，可以自动记录：\n\n- 提示词输入和输出\n- Token 使用量\n- 延迟信息\n- 模型响应元数据\n\n```python\nfrom phoenix.otel import register\n\nregister(\n project_name=\"prompt-playground\",\n endpoint=\"http://localhost:6007/v1/traces\"\n)\n```\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\n# Python\npip install arize-phoenix-client\n\n# TypeScript\nnpm install @arizeai/phoenix-client\n```\n\n### 2. 配置环境变量\n\n```bash\nexport PHOENIX_HOST=\"http://localhost:6006\"\nexport PHOENIX_API_KEY=\"your-api-key\"\n```\n\n### 3. 访问 Playground\n\n启动 Phoenix 后，在浏览器中访问：\n\n```\nhttp://localhost:6006/playground\n```\n\n## 相关资源\n\n- 官方文档：https://arize-ai.github.io/phoenix/\n- GitHub 仓库：https://github.com/Arize-ai/phoenix\n- Slack 社区：https://join.slack.com/t/arize-ai/shared_invite/zt-3r07iavnk-ammtATWSlF0pSrd1DsMW7g\n\n---\n\n\n\n## 前端组件架构\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-002), [部署配置与容器化](#page-009)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [app/src/App.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/App.tsx)\n- [app/src/Routes.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/Routes.tsx)\n- [app/src/pages/TracingRoot.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/TracingRoot.tsx)\n- [app/src/components/trace/TraceTree.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/trace/TraceTree.tsx)\n- [app/src/store/tracingStore.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/store/tracingStore.tsx)\n- [app/src/pages/project/OnboardingSteps.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/OnboardingSteps.tsx)\n- [app/src/components/project/TypeScriptProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/TypeScriptProjectGuide.tsx)\n- [app/src/components/project/PythonProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n- [app/src/components/markdown/streamdownComponents.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/markdown/streamdownComponents.tsx)\n
\n\n# 前端组件架构\n\n## 概述\n\nPhoenix 前端是一个基于 React 的单页应用（SPA），采用 TypeScript 开发，使用 React Router 进行路由管理。该应用主要负责可视化 LLM 应用产生的追踪数据（Traces）、管理项目配置、以及提供评估和实验功能。前端架构遵循组件化设计原则，通过 Zustand 进行状态管理，并使用 Apollo Client 与后端 GraphQL API 通信。\n\n架构的核心目标是提供一个直观的界面，让开发者能够深入了解其 AI 应用的运行时行为，包括追踪调用链、查看 span 详情、分析标注结果等。\n\n---\n\n## 整体架构\n\nPhoenix 前端采用分层架构设计，主要分为以下几个层次：\n\n```mermaid\ngraph TD\n A[App 入口层] --> B[Routes 路由层]\n B --> C[Pages 页面层]\n C --> D[Components 组件层]\n C --> E[Store 状态层]\n D --> F[UI 基础组件]\n D --> G[业务组件]\n E --> H[Zustand Store]\n G --> I[trace/trace 组件]\n G --> J[project/ 项目组件]\n G --> K[markdown/ 渲染组件]\n```\n\n### 层级说明\n\n| 层级 | 职责 | 关键文件 |\n|------|------|----------|\n| **入口层** | 应用初始化、Provider 配置 | `App.tsx` |\n| **路由层** | 路由定义、懒加载 | `Routes.tsx` |\n| **页面层** | 业务页面编排 | `TracingRoot.tsx`, `ProjectTracesPage.tsx` |\n| **组件层** | UI 组件实现 | 各类 `*.tsx` 组件 |\n| **状态层** | 全局状态管理 | `tracingStore.tsx` |\n\n---\n\n## 核心模块\n\n### 1. 路由系统\n\nPhoenix 前端使用 React Router v6 定义应用路由结构。路由配置采用声明式写法，支持嵌套路由和懒加载模式。\n\n资料来源：[app/src/Routes.tsx:1-80](https://github.com/Arize-ai/phoenix/blob/main/app/src/Routes.tsx)\n\n#### 路由配置结构\n\n```mermaid\ngraph LR\n A[/projects] --> B[ProjectLayout]\n B --> C[traces]\n B --> D[evaluations]\n B --> E[prompts]\n B --> F[datasets]\n A --> G[/settings]\n G --> G1[general]\n G --> G2[secrets]\n G --> G3[providers]\n G --> G4[models]\n```\n\n核心路由包括：\n\n| 路径 | 页面组件 | 功能 |\n|------|----------|------|\n| `/projects/:projectId/traces` | `ProjectTracesPage` | 追踪列表与详情 |\n| `/projects/:projectId/evaluations` | 评估页面 | 评估结果管理 |\n| `/projects/:projectId/prompts` | 提示工程页面 | Prompt 版本管理 |\n| `/projects/:projectId/datasets` | 数据集页面 | 数据集编辑 |\n| `/settings/*` | 设置相关页面 | 系统配置 |\n\n#### 路由代码示例\n\n```typescript\n}\n handle={{\n crumb: () => \"Settings\",\n }}\n>\n }\n />\n\n```\n\n资料来源：[app/src/Routes.tsx:45-55](https://github.com/Arize-ai/phoenix/blob/main/app/src/Routes.tsx)\n\n### 2. 追踪根组件\n\n`TracingRoot` 是追踪功能的核心容器组件，负责提供追踪上下文环境。该组件使用 React Context 模式，将追踪相关的状态和操作向下传递给子组件。\n\n资料来源：[app/src/pages/TracingRoot.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/TracingRoot.tsx)\n\n```mermaid\ngraph TD\n A[TracingRoot] --> B[TracePaginationProvider]\n A --> C[SpanFiltersProvider]\n B --> D[TracesTable]\n C --> E[Span 相关组件]\n D --> F[AnnotationTooltip]\n D --> G[AnnotationLabel]\n```\n\n#### TracingRoot 结构\n\n```typescript\nexport const ProjectTracesPage = () => {\n return (\n \n \n \n }>\n \n \n \n \n \n \n \n \n );\n};\n```\n\n资料来源：[app/src/pages/TracingRoot.tsx:60-75](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/TracingRoot.tsx)\n\n### 3. 状态管理\n\nPhoenix 前端使用 Zustand 作为状态管理方案。`tracingStore` 是追踪功能的核心状态存储，管理追踪数据的加载、分页、过滤等状态。\n\n资料来源：[app/src/store/tracingStore.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/store/tracingStore.tsx)\n\n#### 状态管理架构\n\n```mermaid\ngraph LR\n A[用户操作] --> B[tracingStore]\n B --> C[API 调用]\n C --> D[更新状态]\n D --> E[触发 UI 渲染]\n```\n\n#### Store 核心功能\n\n| 功能 | 说明 |\n|------|------|\n| 分页管理 | 管理追踪记录的分页状态 |\n| 过滤条件 | 存储和应用 span 过滤条件 |\n| 查询状态 | 追踪 GraphQL 查询引用 |\n| 选中状态 | 当前选中的 trace/spand ID |\n\n### 4. 追踪树组件\n\n`TraceTree` 组件负责渲染追踪数据的树形结构，展示 trace 与 span 之间的层级关系。\n\n资料来源：[app/src/components/trace/TraceTree.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/trace/TraceTree.tsx)\n\n```mermaid\ngraph TD\n A[TraceTree] --> B[TraceRow]\n A --> C[SpanRow]\n B --> D[展开/折叠]\n C --> E[层级缩进]\n B --> F[元数据展示]\n```\n\n#### 树节点数据结构\n\n```typescript\ninterface TraceNode {\n id: string;\n traceId: string;\n projectId: string;\n children?: TraceNode[];\n metadata: SpanMetadata;\n}\n```\n\n---\n\n## 业务组件\n\n### 1. 项目引导组件\n\n`OnboardingSteps` 是新用户首次使用时的引导组件，帮助用户完成 Phoenix 的初始配置。\n\n资料来源：[app/src/pages/project/OnboardingSteps.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/OnboardingSteps.tsx)\n\n#### 组件 Props\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `language` | `ProgrammingLanguage` | 编程语言类型 |\n| `packages` | `readonly string[]` | 需安装的包列表 |\n| `implementationCode` | `string` | 示例实现代码 |\n| `docsHref` | `string` | 文档链接 |\n| `githubHref` | `string` | GitHub 链接 |\n| `generatedApiKey` | `string \\| null` | 生成的 API Key |\n| `onApiKeyGenerated` | `(key: string) => void` | API Key 生成回调 |\n\n#### 组件功能\n\n1. **环境变量配置**：根据认证状态和部署类型生成相应的环境变量\n2. **文档链接**：提供指向官方文档和 GitHub 的外部链接\n3. **API Key 生成**：支持在托管部署环境下生成项目 API Key\n\n```typescript\nconst envVars = getEnvironmentVariables({\n isAuthEnabled,\n isHosted,\n apiKey: generatedApiKey ?? undefined,\n extraEnvVars,\n});\n```\n\n资料来源：[app/src/pages/project/OnboardingSteps.tsx:75-80](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/project/OnboardingSteps.tsx)\n\n### 2. 项目指南组件\n\nPhoenix 提供针对不同编程语言的项目设置指南组件。\n\n#### TypeScript 项目指南\n\n资料来源：[app/src/components/project/TypeScriptProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/TypeScriptProjectGuide.tsx)\n\n```mermaid\ngraph TD\n A[TypeScriptProjectGuide] --> B[Quick Start 区块]\n A --> C[环境变量区块]\n A --> D[API Key 生成区块]\n B --> E[TypeScript 代码块]\n C --> F[Bash 代码块]\n```\n\n**核心功能：**\n\n- 展示 OpenTelemetry 初始化代码\n- 提供环境变量配置示例\n- 根据认证状态显示 API Key 管理入口\n\n#### Python 项目指南\n\n资料来源：[app/src/components/project/PythonProjectGuide.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/project/PythonProjectGuide.tsx)\n\n**安装依赖部分：**\n\n```typescript\n\n```\n\n**环境变量配置：**\n\n组件自动从环境变量读取配置，无需手动设置。支持的变量包括：\n\n| 变量名 | 用途 |\n|--------|------|\n| `PHOENIX_HOST` | Phoenix 服务器地址 |\n| `PHOENIX_API_KEY` | API 认证密钥 |\n| `PHOENIX_PORT` | HTTP 端口 |\n| `PHOENIX_GRPC_PORT` | gRPC 端口 |\n| `PHOENIX_PROJECT` | 默认项目名称 |\n\n---\n\n## Markdown 渲染组件\n\nPhoenix 前端使用 `streamdownComponents` 实现 Markdown 内容的安全渲染。该组件库基于 `mdast` 和 `hast` 规范，提供自定义的 React 组件映射。\n\n资料来源：[app/src/components/markdown/streamdownComponents.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/markdown/streamdownComponents.tsx)\n\n### 组件映射表\n\n| Markdown 元素 | React 组件 | 样式 |\n|---------------|------------|------|\n| `blockquote` | `
` | `blockquoteCSS` |\n| `inlineCode` | `` | `inlineCodeCSS` |\n| `table` | `MarkdownTable` | 自定义表格组件 |\n| `thead` | `` | `tableSectionHeaderCSS` |\n| `th` | `` | `tableHeaderCellCSS` |\n| `td` | `` | `tableCellCSS` |\n| `img` | `` | `imageCSS` |\n| `hr` | `
` | `hrCSS` |\n\n### 代码块渲染\n\n```typescript\ninlineCode: ({ children, className }) => (\n \n {children}\n \n),\n```\n\n---\n\n## 工具调用展示组件\n\n`DocsToolDetails` 组件负责渲染 AI Agent 工具调用的输入输出信息，包括搜索结果和错误状态。\n\n资料来源：[app/src/components/agent/DocsToolDetails.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/DocsToolDetails.tsx)\n\n### 工具状态渲染\n\n```mermaid\ngraph TD\n A[ToolInvocationPart] --> B{state}\n B -->|input-received| C[显示输入内容]\n B -->|output-available| D[显示输出内容]\n B -->|output-error| E[显示错误信息]\n B -->|其他状态| F[不显示]\n```\n\n### 核心功能\n\n| 功能 | 说明 |\n|------|------|\n| 搜索输入解析 | 解析 `DocsSearchInput` 提取查询字符串 |\n| 页面输入解析 | 解析 `DocsGetPageInput` 提取页面 URL |\n| 输出截断 | `truncateDocsOutput` 函数限制预览长度 |\n\n#### 输出截断函数\n\n```typescript\nexport function truncateDocsOutput(text: string): string {\n if (text.length <= OUTPUT_PREVIEW_LENGTH) {\n return text;\n }\n return text.slice(0, OUTPUT_PREVIEW_LENGTH) + \"…\";\n}\n```\n\n资料来源：[app/src/components/agent/DocsToolDetails.tsx:90-96](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/agent/DocsToolDetails.tsx)\n\n---\n\n## 标注系统组件\n\n### 标注配置列表\n\n`AnnotationConfigList` 组件提供标注配置的选择和管理功能。\n\n资料来源：[app/src/components/trace/AnnotationConfigList.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/trace/AnnotationConfigList.tsx)\n\n### 标注标签组件\n\n在实验运行表格中，标注通过 `AnnotationLabel` 组件展示，支持点击跳转到对应的追踪记录：\n\n```typescript\n {\n if (annotation.trace) {\n navigate(\n `/projects/${annotation.trace.projectId}/traces/${annotation.trace.traceId}`\n );\n }\n }}\n/>\n```\n\n资料来源：[app/src/pages/example/ExampleExperimentRunsTable.tsx:1-50](https://github.com/Arize-ai/phoenix/blob/main/app/src/pages/example/ExampleExperimentRunsTable.tsx)\n\n---\n\n## 配置与常量\n\n### 环境变量解析\n\nPhoenix 前端提供 `@arizeai/phoenix-config` 包用于解析环境变量：\n\n资料来源：[js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n| 变量名 | 常量 | 描述 |\n|--------|------|------|\n| `PHOENIX_HOST` | `ENV_PHOENIX_HOST` | 服务器地址 |\n| `PHOENIX_API_KEY` | `ENV_PHOENIX_API_KEY` | API 密钥 |\n| `PHOENIX_COLLECTOR_ENDPOINT` | `ENV_PHOENIX_COLLECTOR_ENDPOINT` | OTel 收集器端点 |\n| `PHOENIX_PORT` | `ENV_PHOENIX_PORT` | HTTP 端口 |\n| `PHOENIX_GRPC_PORT` | `ENV_PHOENIX_GRPC_PORT` | gRPC 端口 |\n| `PHOENIX_PROJECT` | `ENV_PHOENIX_PROJECT` | 默认项目名 |\n\n---\n\n## 组件目录结构\n\n```\napp/src/\n├── App.tsx # 应用入口\n├── Routes.tsx # 路由配置\n├── pages/\n│ ├── TracingRoot.tsx # 追踪根组件\n│ ├── project/\n│ │ ├── ProjectTracesPage.tsx\n│ │ └── OnboardingSteps.tsx\n│ └── example/\n│ └── ExampleExperimentRunsTable.tsx\n├── components/\n│ ├── trace/\n│ │ ├── TraceTree.tsx\n│ │ ├── AnnotationConfigList.tsx\n│ │ └── DocumentItem.tsx\n│ ├── project/\n│ │ ├── TypeScriptProjectGuide.tsx\n│ │ ├── PythonProjectGuide.tsx\n│ │ └── IntegrationIcons.tsx\n│ ├── agent/\n│ │ └── DocsToolDetails.tsx\n│ ├── markdown/\n│ │ └── streamdownComponents.tsx\n│ ├── core/icon/\n│ │ └── Icons.tsx\n│ └── playground/\n│ └── PromptMenu.tsx\n└── store/\n └── tracingStore.tsx # 状态管理\n```\n\n---\n\n## 技术栈总结\n\n| 类别 | 技术选型 |\n|------|----------|\n| 框架 | React 18+ |\n| 语言 | TypeScript |\n| 路由 | React Router v6 |\n| 状态管理 | Zustand |\n| 数据获取 | Apollo Client (GraphQL) |\n| 样式方案 | CSS-in-JS (内联样式) |\n| UI 组件库 | 内部构建 + Adobe Spectrum |\n| Markdown 渲染 | streamdown |\n| 构建工具 | Vite |\n\n---\n\n## 开发指南\n\n### 新增页面\n\n1. 在 `pages/` 目录下创建页面组件\n2. 在 `Routes.tsx` 中注册路由\n3. 添加面包屑导航配置：\n\n```typescript\n}\n handle={{\n crumb: () => \"新页面\",\n }}\n/>\n```\n\n### 新增组件\n\n1. 根据组件类型选择合适的目录\n2. 遵循现有组件的 props 类型定义模式\n3. 使用 `export` 导出以便复用\n\n### 状态管理\n\n在 `tracingStore.tsx` 中添加新的状态切片：\n\n```typescript\nconst useTracingStore = create()((set) => ({\n // 现有状态\n newState: initialValue,\n setNewState: (value) => set({ newState: value }),\n}));\n\n---\n\n\n\n## 部署配置与容器化\n\n### 相关页面\n\n相关主题：[前端组件架构](#page-008), [系统架构设计](#page-002)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [Dockerfile](https://github.com/Arize-ai/phoenix/blob/main/Dockerfile)\n- [docker-compose.yml](https://github.com/Arize-ai/phoenix/blob/main/docker-compose.yml)\n- [helm/Chart.yaml](https://github.com/Arize-ai/phoenix/blob/main/helm/Chart.yaml)\n- [helm/values.yaml](https://github.com/Arize-ai/phoenix/blob/main/helm/values.yaml)\n- [src/phoenix/config.py](https://github.com/Arize-ai/phoenix/blob/main/src/phoenix/config.py)\n
\n\n# 部署配置与容器化\n\nPhoenix 是一个开源的可观测性平台，支持多种部署方式，包括 Docker 容器化部署和 Kubernetes 集群部署。本页面详细介绍 Phoenix 的环境变量配置、Docker 部署方案以及 Helm Chart 部署方式。\n\n## 环境变量配置\n\nPhoenix 使用环境变量进行运行时配置，这些变量贯穿整个应用程序的生命周期。\n\n### 核心配置变量\n\n| 变量名 | 常量定义 | 类型 | 说明 |\n|--------|----------|------|------|\n| `PHOENIX_HOST` | `ENV_PHOENIX_HOST` | 字符串 | Phoenix 服务器主机地址，格式为 `http://localhost:6006` |\n| `PHOENIX_API_KEY` | `ENV_PHOENIX_API_KEY` | 字符串 | 用于 Phoenix 身份验证的 API 密钥 |\n| `PHOENIX_CLIENT_HEADERS` | `ENV_PHOENIX_CLIENT_HEADERS` | JSON | 客户端请求的自定义请求头 |\n| `PHOENIX_COLLECTOR_ENDPOINT` | `ENV_PHOENIX_COLLECTOR_ENDPOINT` | 字符串 | OpenTelemetry 收集器端点 URL |\n| `PHOENIX_PORT` | `ENV_PHOENIX_PORT` | 整数 | Phoenix HTTP 端口 |\n| `PHOENIX_GRPC_PORT` | `ENV_PHOENIX_GRPC_PORT` | 整数 | OpenTelemetry gRPC 端口 |\n| `PHOENIX_PROJECT` | `ENV_PHOENIX_PROJECT` | 字符串 | 项目操作的默认项目名称 |\n\n资料来源：[js/packages/phoenix-config/README.md]()\n\n### 配置读取机制\n\nPhoenix 的配置模块提供了类型化的配置读取辅助函数。这些辅助函数能够：\n\n- 自动从环境变量中读取配置值\n- 提供类型安全的配置访问接口\n- 支持默认值和必需配置项的验证\n\n```typescript\n// TypeScript 客户端配置示例\nimport { register } from \"@arizeai/phoenix-otel\";\n\nregister({\n projectName: \"my-app\",\n url: \"https://app.phoenix.arize.com\",\n apiKey: process.env.PHOENIX_API_KEY,\n});\n```\n\n资料来源：[js/packages/phoenix-otel/README.md]()\n\n## Docker 部署\n\nPhoenix 提供官方 Docker 镜像，支持单机快速部署场景。\n\n### Docker 镜像架构\n\n```mermaid\ngraph TD\n A[phoenix Docker Image] --> B[Python Runtime]\n A --> C[Phoenix Application]\n A --> D[OpenTelemetry Collector]\n B --> C\n C --> E[SQLite/数据库]\n D --> C\n```\n\n### 端口配置\n\nPhoenix 容器使用以下默认端口：\n\n| 端口 | 协议 | 用途 |\n|------|------|------|\n| 6006 | HTTP | Phoenix Web UI |\n| 4317 | gRPC | OpenTelemetry 接收 |\n| 4318 | HTTP | OpenTelemetry 接收 |\n\n### 环境变量配置\n\n在 Docker 环境中，可通过 `-e` 参数或 `.env` 文件传递配置：\n\n```bash\ndocker run -d \\\n -p 6006:6006 \\\n -e PHOENIX_PORT=6006 \\\n -e PHOENIX_GRPC_PORT=4317 \\\n -e PHOENIX_HOST=http://localhost:6006 \\\n arizephoenix/phoenix:latest\n```\n\n## Docker Compose 部署\n\n对于本地开发和多服务协作场景，Phoenix 支持 Docker Compose 编排部署。\n\n### 服务编排架构\n\n```mermaid\ngraph LR\n A[Phoenix Container] --> B[SQLite Volume]\n A --> C[OpenTelemetry Collector]\n D[Application] -->|Traces| C\n C -->|Export| A\n```\n\n### docker-compose.yml 结构\n\n典型配置文件包含以下服务定义：\n\n- **phoenix**：主应用程序服务\n- **collector**：OpenTelemetry 收集器服务\n- **volumes**：持久化存储卷\n\n```yaml\nservices:\n phoenix:\n image: arizephoenix/phoenix:latest\n ports:\n - \"6006:6006\"\n environment:\n - PHOENIX_PORT=6006\n - PHOENIX_GRPC_PORT=4317\n volumes:\n - phoenix-data:/data\n\n collector:\n image: otel/opentelemetry-collector-contemporary\n ports:\n - \"4317:4317\"\n - \"4318:4318\"\n```\n\n## Kubernetes 部署\n\nPhoenix 提供 Helm Chart 用于 Kubernetes 集群部署，支持生产环境的高可用配置。\n\n### Helm Chart 架构\n\n```mermaid\ngraph TD\n A[Phoenix Helm Release] --> B[Deployment]\n A --> C[Service]\n A --> D[ConfigMap]\n A --> E[Ingress]\n B --> F[Pod: phoenix-app]\n F --> G[ConfigMap: 环境变量]\n F --> H[Secret: API密钥]\n```\n\n### Chart 配置\n\nChart.yaml 定义了 Chart 的基本元数据：\n\n| 字段 | 说明 |\n|------|------|\n| `name` | Chart 名称 |\n| `version` | Chart 版本 |\n| `appVersion` | Phoenix 应用版本 |\n| `kubeVersion` | 支持的 Kubernetes 版本范围 |\n\n### values.yaml 配置选项\n\nHelm Chart 通过 values.yaml 提供灵活的部署配置：\n\n```yaml\n# 镜像配置\nimage:\n repository: arizephoenix/phoenix\n tag: latest\n pullPolicy: IfNotPresent\n\n# 副本配置\nreplicaCount: 1\n\n# 服务配置\nservice:\n type: ClusterIP\n port: 6006\n grpcPort: 4317\n\n# 环境变量配置\nenv:\n PHOENIX_HOST: \"\"\n PHOENIX_PORT: \"6006\"\n PHOENIX_GRPC_PORT: \"4317\"\n PHOENIX_PROJECT: \"default\"\n\n# 资源限制\nresources:\n limits:\n cpu: 1000m\n memory: 2Gi\n requests:\n cpu: 100m\n memory: 512Mi\n\n# Ingress 配置\ningress:\n enabled: false\n className: \"\"\n annotations: {}\n hosts:\n - host: phoenix.local\n paths:\n - path: /\n pathType: Prefix\n```\n\n### 部署命令\n\n```bash\n# 添加 Helm 仓库\nhelm repo add arize https://arize-ai.github.io/phoenix\n\n# 安装 Phoenix\nhelm install phoenix arize/phoenix\n\n# 自定义配置部署\nhelm install phoenix arize/phoenix -f custom-values.yaml\n\n# 查看部署状态\nhelm status phoenix\n\n# 升级版本\nhelm upgrade phoenix arize/phoenix --set image.tag=v2.0.0\n```\n\n## Python SDK 配置\n\nPython 应用程序通过 `arize-phoenix-otel` 包与 Phoenix 集成。\n\n### 自动环境变量读取\n\n`arize-phoenix-otel` 包会自动从环境变量中读取配置，无需显式编码：\n\n```python\nimport os\n\n# 设置环境变量\nos.environ[\"PHOENIX_HOST\"] = \"http://localhost:6006\"\nos.environ[\"PHOENIX_API_KEY\"] = \"your-api-key\"\nos.environ[\"PHOENIX_PROJECT\"] = \"my-project\"\n```\n\n### OTEL 初始化代码\n\n```python\nfrom phoenix.otel import register\n\n# 注册 Phoenix 作为 OTEL provider\nprovider = register(project_name=\"my-app\")\n\n# 你的应用代码...\n\n# 关闭时清理资源\nawait provider.shutdown()\n```\n\n资料来源：[app/src/components/project/PythonProjectGuide.tsx]()\n\n## 认证与安全配置\n\n### API Key 配置\n\n当启用认证时，Phoenix 需要 API Key 进行身份验证：\n\n| 配置方式 | 适用场景 | 配置路径 |\n|----------|----------|----------|\n| 个人 API Key | 单用户开发 | `/profile` 页面管理 |\n| 系统 API Key | 服务间通信 | `/settings/general` 页面管理 |\n\n```typescript\n// TypeScript 客户端认证配置\nconst client = new PhoenixClient({\n host: process.env.PHOENIX_HOST,\n apiKey: process.env.PHOENIX_API_KEY,\n headers: {\n \"X-Custom-Header\": \"value\"\n }\n});\n```\n\n### 自定义请求头配置\n\n通过 `PHOENIX_CLIENT_HEADERS` 环境变量设置自定义请求头：\n\n```bash\n# JSON 格式编码的自定义头\nPHOENIX_CLIENT_HEADERS='{\"X-Org-Id\": \"12345\", \"X-Team\": \"ml-team\"}'\n```\n\n资料来源：[js/packages/phoenix-client/README.md]()\n\n## MCP 服务器配置\n\nPhoenix MCP (Model Context Protocol) 服务器支持独立的开发部署。\n\n### 开发环境配置\n\n创建 `.env` 文件配置 MCP 服务器：\n\n```bash\nPHOENIX_API_KEY=your-api-key\nPHOENIX_HOST=https://my-phoenix.com\nPHOENIX_PROJECT=default-project\nPHOENIX_CLIENT_HEADERS={}\n```\n\n### MCP 服务器启动\n\n```json\n{\n \"mcpServers\": {\n \"phoenix\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@arizeai/phoenix-mcp@latest\",\n \"--baseUrl\",\n \"https://my-phoenix.com\",\n \"--apiKey\",\n \"your-api-key\"\n ]\n }\n }\n}\n```\n\n资料来源：[js/packages/phoenix-mcp/README.md]()\n\n## 部署架构总览\n\n```mermaid\ngraph TB\n subgraph \"客户端层\"\n A[Python App
arize-phoenix-otel]\n B[TypeScript App
@arizeai/phoenix-otel]\n C[CLI Agent
phoenix-cli]\n end\n\n subgraph \"网络层\"\n D[Ingress Controller]\n E[Load Balancer]\n end\n\n subgraph \"Kubernetes 集群\"\n F[Phoenix Pod]\n G[OTEL Collector Pod]\n H[PostgreSQL/MySQL]\n end\n\n A -->|OTLP Protocol| G\n B -->|OTLP Protocol| G\n C -->|REST API| F\n G -->|Export| F\n D --> F\n E --> D\n F --> H\n```\n\n## 常见部署场景\n\n### 本地开发环境\n\n```bash\n# 使用 Docker Compose 快速启动\ndocker-compose up -d\n\n# 或使用 pnpm 开发模式\ncd js\npnpm install\npnpm dev\n```\n\n### 生产环境部署\n\n```bash\n# 1. 创建 Kubernetes 命名空间\nkubectl create namespace phoenix\n\n# 2. 创建 Secret 存储 API Key\nkubectl create secret generic phoenix-secrets \\\n --from-literal=PHOENIX_API_KEY=your-key \\\n --namespace phoenix\n\n# 3. 安装 Helm Chart\nhelm install phoenix arize/phoenix \\\n --namespace phoenix \\\n --set ingress.enabled=true \\\n --set ingress.hostname=phoenix.example.com \\\n --set replicaCount=3\n```\n\n### 云端托管部署\n\n对于云端托管的 Phoenix Cloud，使用生产配置：\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\n\nregister({\n projectName: \"production-app\",\n url: \"https://app.phoenix.arize.com\",\n apiKey: process.env.PHOENIX_API_KEY,\n});\n```\n\n## 配置优先级\n\nPhoenix 配置按以下优先级生效（从高到低）：\n\n1. **代码级别配置**：直接在代码中传递的参数\n2. **环境变量**：运行时环境变量\n3. **配置文件**：values.yaml 或 config.py 中的默认值\n4. **编译时默认值**：镜像内置的默认值\n\n## 故障排查\n\n### 常见配置问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 连接被拒绝 | 端口配置不匹配 | 检查 `PHOENIX_PORT` 和容器端口映射 |\n| 认证失败 | API Key 无效 | 验证 `PHOENIX_API_KEY` 配置 |\n| gRPC 连接失败 | 防火墙阻止 | 开放 4317 端口或检查 `PHOENIX_GRPC_PORT` |\n| 配置不生效 | 缓存问题 | 重启 Pod 或清除缓存 |\n\n### 诊断命令\n\n```bash\n# 查看 Phoenix 日志\nkubectl logs -n phoenix deployment/phoenix\n\n# 检查服务健康状态\ncurl http://phoenix-service:6006/health\n\n# 验证环境变量\nkubectl exec -n phoenix deployment/phoenix -- env | grep PHOENIX\n\n---\n\n\n\n## Python SDK 参考\n\n### 相关页面\n\n相关主题：[Tracing 系统实现](#page-004)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [packages/phoenix-client/src/phoenix/client/client.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/client.py)\n- [packages/phoenix-otel/src/phoenix/otel/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-otel/src/phoenix/otel/__init__.py)\n- [packages/phoenix-client/src/phoenix/client/resources/spans/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/spans/__init__.py)\n- [packages/phoenix-client/src/phoenix/client/resources/traces/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/traces/__init__.py)\n- [packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/README.md)\n- [js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n
\n\n# Python SDK 参考\n\nPhoenix Python SDK 是 Arize Phoenix 平台的核心客户端库，提供与 Phoenix REST API 交互的完整接口，支持追踪管理、数据集操作、实验运行和评估反馈等功能。\n\n## 概述\n\nPhoenix Python SDK 主要包含两个核心包：\n\n| 包名 | 功能描述 |\n|------|----------|\n| `arize-phoenix-client` | REST API 客户端，支持同步和异步操作 |\n| `arize-phoenix-otel` | OpenTelemetry 集成，用于自动采集追踪数据 |\n\nSDK 支持以下主要功能：\n\n- **追踪管理**：查询和分析分布式追踪数据\n- **跨度操作**：检索和过滤跨度（Span）信息\n- **数据集管理**：创建、追加和版本化管理数据集\n- **实验跟踪**：运行评估实验并追踪结果\n- **评估注释**：添加人工反馈和自动化评估\n\n资料来源：[packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/README.md)\n\n## 安装\n\n使用 pip 安装 Phoenix Python 客户端：\n\n```bash\npip install arize-phoenix-client\n```\n\n对于需要 OpenTelemetry 集成的场景：\n\n```bash\npip install arize-phoenix-otel\n```\n\n资料来源：[packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/README.md)\n\n## 核心架构\n\n### 架构图\n\n```mermaid\ngraph TD\n A[应用程序] --> B[OpenTelemetry SDK]\n A --> C[Phoenix Client]\n B --> D[OTLP Exporter]\n D --> E[Phoenix Collector]\n C --> E\n E --> F[(Phoenix Database)]\n \n G[追踪数据] --> H[Spans API]\n G --> I[Traces API]\n C --> H\n C --> I\n```\n\n### 组件层次\n\n| 层级 | 组件 | 说明 |\n|------|------|------|\n| 用户层 | Phoenix Client | 直接与 REST API 交互 |\n| 用户层 | Phoenix OTEL | 自动instrumentation |\n| 传输层 | OTLP Exporter | OpenTelemetry 协议导出 |\n| 服务层 | Phoenix Server | 数据接收和存储 |\n\n## 环境变量配置\n\nPhoenix SDK 支持通过环境变量自动配置：\n\n| 环境变量 | 说明 | 默认值 |\n|----------|------|--------|\n| `PHOENIX_BASE_URL` | Phoenix 服务器地址 | `http://localhost:6006` |\n| `PHOENIX_API_KEY` | API 认证密钥 | `undefined` |\n| `PHOENIX_CLIENT_HEADERS` | 自定义请求头（JSON格式） | `{}` |\n| `PHOENIX_COLLECTOR_ENDPOINT` | OTel 收集器端点 | `http://localhost:6006` |\n| `PHOENIX_PORT` | Phoenix HTTP 端口 | `6006` |\n| `PHOENIX_GRPC_PORT` | Phoenix gRPC 端口 | `4317` |\n| `PHOENIX_PROJECT` | 默认项目名称 | `default` |\n\n### 云端配置示例\n\n```bash\n# 本地 Phoenix 服务器\nexport PHOENIX_BASE_URL=\"http://localhost:6006\"\n\n# Phoenix 云端实例\nexport PHOENIX_API_KEY=\"your-api-key\"\nexport PHOENIX_BASE_URL=\"https://app.phoenix.arize.com/s/your-space\"\n\n# 自定义请求头\nexport PHOENIX_CLIENT_HEADERS=\"Authorization=Bearer your-api-key,custom-header=value\"\n```\n\n资料来源：[js/packages/phoenix-config/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-config/README.md)\n\n## 客户端初始化\n\n### 同步客户端\n\n```python\nfrom phoenix.client import Client\n\n# 自动从环境变量读取配置\nclient = Client()\n\n# 显式指定配置\nclient = Client(base_url=\"http://localhost:6006\")\n\n# 云端实例带 API 密钥\nclient = Client(\n base_url=\"https://app.phoenix.arize.com/s/your-space\",\n api_key=\"your-api-key\"\n)\n\n# 自定义认证头\nclient = Client(\n base_url=\"https://your-phoenix-instance.com\",\n headers={\"Authorization\": \"Bearer your-api-key\"}\n)\n```\n\n### 异步客户端\n\n```python\nfrom phoenix.client import AsyncClient\n\n# 异步客户端（支持相同配置选项）\nasync_client = AsyncClient()\nasync_client = AsyncClient(base_url=\"http://localhost:6006\")\nasync_client = AsyncClient(\n base_url=\"https://app.phoenix.arize.com/s/your-space\",\n api_key=\"your-api-key\"\n)\n```\n\n资料来源：[packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/README.md)\n\n## Spans API\n\nSpans API 提供对追踪中跨度的查询和分析能力。\n\n### 主要功能\n\n- 查询跨度数据并支持强大的过滤条件\n- 提取跨度属性用于 RAG 评估工作流\n- 获取特定项目的跨度列表\n\n### 使用示例\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# 获取项目中的跨度列表\nspans = client.spans.list_spans(project_name=\"my-project\")\n\n# 过滤特定类型的跨度\nllm_spans = client.spans.list_spans(\n project_name=\"my-project\",\n span_type=\"llm\"\n)\n\n# 获取跨度详情\nspan = client.spans.get_span(span_id=\"span-123\")\n```\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources/spans/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/spans/__init__.py)\n\n## Traces API\n\nTraces API 用于追踪级别的操作和查询。\n\n### 主要功能\n\n- 列出项目中的追踪\n- 获取追踪详情\n- 过滤和搜索追踪数据\n\n### 使用示例\n\n```python\nfrom phoenix.client import Client\n\nclient = Client()\n\n# 获取追踪列表\ntraces = client.traces.list_traces(project_name=\"my-project\")\n\n# 按时间范围过滤\nrecent_traces = client.traces.list_traces(\n project_name=\"my-project\",\n start_time=\"2024-01-01T00:00:00Z\",\n end_time=\"2024-01-31T23:59:59Z\"\n)\n```\n\n资料来源：[packages/phoenix-client/src/phoenix/client/resources/traces/__init__.py](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/src/phoenix/client/resources/traces/__init__.py)\n\n## Datasets API\n\n### 功能概述\n\n- 从 DataFrame、CSV 文件或字典创建数据集\n- 追加数据到现有数据集\n- 版本化管理数据集\n\n### 使用示例\n\n```python\nfrom phoenix.client import Client\nimport pandas as pd\n\nclient = Client()\n\n# 从 DataFrame 创建数据集\ndf = pd.DataFrame({\n \"input\": [\"What is Phoenix?\", \"How to install?\"],\n \"output\": [\"Phoenix is...\", \"Run pip install...\"]\n})\ndataset = client.datasets.create_dataset(\n name=\"my-dataset\",\n dataframe=df\n)\n\n# 获取数据集\ndataset = client.datasets.get_dataset(\n dataset=\"my-dataset\",\n version_id=\"v1.0.0\" # 可选，指定版本\n)\n\n# 追加数据\nclient.datasets.append_to_dataset(\n dataset_name=\"my-dataset\",\n dataframe=new_df\n)\n```\n\n资料来源：[packages/phoenix-client/README.md](https://github.com/Arize-ai/phoenix/blob/main/packages/phoenix-client/README.md)\n\n## OpenTelemetry 集成\n\n### 快速开始\n\n```typescript\nimport { register } from \"@arizeai/phoenix-otel\";\n\nregister({\n projectName: \"my-app\",\n url: \"https://app.phoenix.arize.com\",\n apiKey: process.env.PHOENIX_API_KEY,\n});\n```\n\n### 配置选项\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `projectName` | `string` | `\"default\"` | 项目名称 |\n| `url` | `string` | `\"http://localhost:6006\"` | Phoenix 实例 URL |\n| `apiKey` | `string` | `undefined` | API 认证密钥 |\n| `headers` | `Record` | `{}` | 自定义请求头 |\n| `batch` | `boolean` | `true` | 使用批量跨度处理 |\n| `instrumentations` | `Instrumentation[]` | `undefined` | OpenTelemetry instrumentations |\n\n### Python 端环境变量配置\n\n```bash\n# 本地 Phoenix 服务器\nexport PHOENIX_COLLECTOR_ENDPOINT=\"http://localhost:6006\"\n\n# Phoenix 云端\nexport PHOENIX_COLLECTOR_ENDPOINT=\"https://app.phoenix.arize.com\"\nexport PHOENIX_API_KEY=\"your-api-key\"\n```\n\n资料来源：[js/packages/phoenix-otel/README.md](https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-otel/README.md)\n\n## 认证机制\n\n### API Key 认证\n\nPhoenix 支持多种认证方式：\n\n```python\nfrom phoenix.client import Client\n\n# 方式一：环境变量\n# 设置 PHOENIX_API_KEY 环境变量\nclient = Client()\n\n# 方式二：客户端初始化时传入\nclient = Client(\n base_url=\"https://app.phoenix.arize.com/s/your-space\",\n api_key=\"your-api-key\"\n)\n```\n\n### OpenTelemetry SDK 认证\n\n当使用 OpenTelemetry SDK 时，通过环境变量配置认证：\n\n```bash\n# 方式一：环境变量\nexport PHOENIX_API_KEY=\"your-api-key\"\n\n# 方式二：OTEL 头信息\nexport OTEL_EXPORTER_OTLP_HEADERS=\"Authorization=Bearer your-api-key\"\n```\n\n### REST/GraphQL API 认证\n\n```bash\n# Bearer Token 认证\nAuthorization: Bearer your-api-key\n```\n\n资料来源：[app/src/components/auth/OneTimeAPIKeyDialog.tsx](https://github.com/Arize-ai/phoenix/blob/main/app/src/components/auth/OneTimeAPIKeyDialog.tsx)\n\n## 数据流架构\n\n```mermaid\nsequenceDiagram\n participant App as 应用程序\n participant OTel as OpenTelemetry SDK\n participant Exporter as OTLP Exporter\n participant Phoenix as Phoenix Server\n participant Client as Phoenix Client\n \n App->>OTel: 业务逻辑执行\n OTel->>OTel: 自动instrumentation\n OTel->>Exporter: 发送Span数据\n Exporter->>Phoenix: HTTP/gRPC传输\n Phoenix->>Phoenix: 存储到数据库\n \n App->>Client: API请求\n Client->>Phoenix: REST API调用\n Phoenix->>Client: 返回数据\n Client->>App: 查询结果\n```\n\n## 最佳实践\n\n### 1. 客户端管理\n\n```python\n# 推荐：使用上下文管理器\nfrom phoenix.client import Client\n\nwith Client() as client:\n spans = client.spans.list_spans(project_name=\"my-project\")\n # 自动处理连接关闭\n\n# 不推荐：手动管理生命周期\nclient = Client()\n# ... 使用 client\n# client.close() # 容易遗漏\n```\n\n### 2. 环境配置\n\n```python\nimport os\n\n# 显式环境变量设置优于硬编码\nbase_url = os.getenv(\"PHOENIX_BASE_URL\", \"http://localhost:6006\")\napi_key = os.getenv(\"PHOENIX_API_KEY\")\n\nclient = Client(\n base_url=base_url,\n api_key=api_key\n)\n```\n\n### 3. 错误处理\n\n```python\nfrom phoenix.client import Client\nfrom phoenix.exceptions import PhoenixError\n\ntry:\n client = Client()\n dataset = client.datasets.get_dataset(dataset=\"my-dataset\")\nexcept PhoenixError as e:\n print(f\"获取数据集失败: {e}\")\n```\n\n### 4. 性能优化\n\n- 生产环境启用批量处理（默认 `batch=true`）\n- 使用异步客户端处理大量请求\n- 合理设置过滤条件减少数据传输\n\n## 类型定义\n\nSDK 提供完整的类型提示支持：\n\n```python\nfrom phoenix.client import Client\nfrom phoenix.client.resources.spans import SpanModel\n\nclient = Client()\n\n# 类型安全的响应\nspans: list[SpanModel] = client.spans.list_spans(project_name=\"my-project\")\n\nfor span in spans:\n print(span.span_id, span.name, span.attributes)\n```\n\n## 相关资源\n\n- **完整 API 文档**：访问 [Phoenix 官方文档](https://arize-ai.github.io/phoenix/)\n- **示例代码**：查看 `examples/` 目录下的 Jupyter Notebook\n- **集成指南**：参考 [Integrations](https://arize.com/docs/phoenix/tracing/integrations-tracing/openai) 了解各框架集成\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Arize-ai/phoenix\n\n摘要：发现 17 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:564072810 | https://github.com/Arize-ai/phoenix | README/documentation is current enough for a first validation pass.\n\n## 2. 运行坑 · 来源证据：arize-phoenix: v15.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.3.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d364a0a28a14428baff5ca692cb00578 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.3.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 运行坑 · 来源证据：arize-phoenix: v15.5.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ad2696a72e314b52b79d157bf261f7bd | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 运行坑 · 来源证据：arize-phoenix: v15.5.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b75368026b414d1bbe31d7d3e90b2731 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 运行坑 · 来源证据：arize-phoenix: v15.6.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.6.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49d41c4c92f24db2b382ebd014f9bd14 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.6.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：arize-phoenix: v15.7.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.7.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_826b7f8e0d2342cabfedab3cabb1a2dc | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.7.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 运行坑 · 来源证据：arize-phoenix: v15.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.9.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0d47708aa40b4b99b3f132751181cf43 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.9.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:564072810 | https://github.com/Arize-ai/phoenix | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:564072810 | https://github.com/Arize-ai/phoenix | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_547816d87273465a88a09397fc2c4ab1 | https://github.com/Arize-ai/phoenix/issues/13241 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：[security] setup deepsec\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[security] setup deepsec\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_153e6ddc8487493e893542da4c348bbe | https://github.com/Arize-ai/phoenix/issues/13275 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：arize-phoenix: v15.10.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.10.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ce89c62b10a43288f4c6394276bc97c | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.10.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：arize-phoenix: v15.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.4.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fea401ed7b774dc7885c245774e87cce | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.4.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：arize-phoenix: v15.8.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.8.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2ecb08e3e7e04b60ac87fab18439546d | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.8.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "Human Manual / 人类版说明书" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log / 踩坑日志\n\n项目：Arize-ai/phoenix\n\n摘要：发现 17 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:564072810 | https://github.com/Arize-ai/phoenix | README/documentation is current enough for a first validation pass.\n\n## 2. 运行坑 · 来源证据：arize-phoenix: v15.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.3.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d364a0a28a14428baff5ca692cb00578 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.3.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 运行坑 · 来源证据：arize-phoenix: v15.5.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ad2696a72e314b52b79d157bf261f7bd | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 运行坑 · 来源证据：arize-phoenix: v15.5.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.5.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b75368026b414d1bbe31d7d3e90b2731 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.5.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 运行坑 · 来源证据：arize-phoenix: v15.6.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.6.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49d41c4c92f24db2b382ebd014f9bd14 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.6.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 运行坑 · 来源证据：arize-phoenix: v15.7.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.7.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_826b7f8e0d2342cabfedab3cabb1a2dc | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.7.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 运行坑 · 来源证据：arize-phoenix: v15.9.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：arize-phoenix: v15.9.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0d47708aa40b4b99b3f132751181cf43 | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.9.0 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 8. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | last_activity_observed missing\n\n## 9. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:564072810 | https://github.com/Arize-ai/phoenix | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:564072810 | https://github.com/Arize-ai/phoenix | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 来源证据：GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：GenerativeModelStore: _last_fetch_id can regress and defeat incremental fetch\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_547816d87273465a88a09397fc2c4ab1 | https://github.com/Arize-ai/phoenix/issues/13241 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：[security] setup deepsec\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[security] setup deepsec\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_153e6ddc8487493e893542da4c348bbe | https://github.com/Arize-ai/phoenix/issues/13275 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：arize-phoenix: v15.10.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.10.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1ce89c62b10a43288f4c6394276bc97c | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.10.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：arize-phoenix: v15.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.4.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fea401ed7b774dc7885c245774e87cce | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.4.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：arize-phoenix: v15.8.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：arize-phoenix: v15.8.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2ecb08e3e7e04b60ac87fab18439546d | https://github.com/Arize-ai/phoenix/releases/tag/arize-phoenix-v15.8.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:564072810 | https://github.com/Arize-ai/phoenix | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# phoenix - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 phoenix 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-001：项目介绍与快速开始。围绕“项目介绍与快速开始”模拟一次用户任务，不展示安装或运行结果。\n2. page-002：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n3. page-003：数据库模型与迁移。围绕“数据库模型与迁移”模拟一次用户任务，不展示安装或运行结果。\n4. page-004：Tracing 系统实现。围绕“Tracing 系统实现”模拟一次用户任务，不展示安装或运行结果。\n5. page-005：Evaluation 评估系统。围绕“Evaluation 评估系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-001\n输入：用户提供的“项目介绍与快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-002\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-003\n输入：用户提供的“数据库模型与迁移”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-004\n输入：用户提供的“Tracing 系统实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-005\n输入：用户提供的“Evaluation 评估系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-001：Step 1 必须围绕“项目介绍与快速开始”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-002：Step 2 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-003：Step 3 必须围绕“数据库模型与迁移”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-004：Step 4 必须围绕“Tracing 系统实现”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-005：Step 5 必须围绕“Evaluation 评估系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Arize-ai/phoenix\n- https://github.com/Arize-ai/phoenix#readme\n- .agents/skills/agent-browser/SKILL.md\n- .agents/skills/mintlify/SKILL.md\n- .agents/skills/phoenix-cli/SKILL.md\n- .agents/skills/phoenix-design/SKILL.md\n- .agents/skills/phoenix-docs-gap-audit/SKILL.md\n- .agents/skills/phoenix-evals/SKILL.md\n- .agents/skills/phoenix-evals-new-metric/SKILL.md\n- .agents/skills/phoenix-frontend/SKILL.md\n- .agents/skills/phoenix-github/SKILL.md\n- .agents/skills/phoenix-integration-snippets/SKILL.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 phoenix 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：Arize-ai/phoenix\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install arize-phoenix\n```\n\n来源：https://github.com/Arize-ai/phoenix#readme\n\n## 来源\n\n- repo: https://github.com/Arize-ai/phoenix\n- docs: https://github.com/Arize-ai/phoenix#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_18c54a158d1a480fa58695632ed35440" }