{ "canonical_name": "openlit/openlit", "compilation_id": "pack_cf6e6791db7e4e8cab77f877e5344c40", "created_at": "2026-05-16T21:13:00.822719+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=prompt, recipe, host_instruction, eval, preflight", "recommended_asset_types=prompt, 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 openlit` 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 openlit", "sandbox_container_image": "python:3.12-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "llm_execute_isolated_install", "sandbox_validation_id": "sbx_7a347252a92446b598c1b1d2c454d187" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_f5114bcff7bb9c22130b8491cafb6ec8", "canonical_name": "openlit/openlit", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/openlit/openlit", "slug": "openlit", "source_packet_id": "phit_89ffc7f190094e568bb47dc3666592de", "source_validation_id": "dval_bc021b9f126d4942b10ce3ce4d4df599" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 local_cli的用户", "github_forks": 276, "github_stars": 2446, "one_liner_en": "Open source platform for AI Engineering: OpenTelemetry-native LLM Observability, GPU Monitoring, Guardrails, Evaluations, Prompt Management, Vault, Playground. 🚀💻 Integrates with 50+ LLM Providers, VectorDBs, Agent Frameworks and GPUs.", "one_liner_zh": "Open source platform for AI Engineering: OpenTelemetry-native LLM Observability, GPU Monitoring, Guardrails, Evaluations, Prompt Management, Vault, Playground. 🚀💻 Integrates with 50+ LLM Providers, VectorDBs, Agent Frameworks and GPUs.", "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": "openlit", "title_zh": "openlit 能力包", "visible_tags": [ { "label_en": "MCP Tools", "label_zh": "MCP 工具", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-mcp-tools", "type": "product_domain" }, { "label_en": "Knowledge Base Q&A", "label_zh": "知识库问答", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-knowledge-base-q-a", "type": "user_job" }, { "label_en": "Workflow Automation", "label_zh": "流程自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-workflow-automation", "type": "core_capability" }, { "label_en": "Checkpoint Resume", "label_zh": "断点恢复流程", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-checkpoint-resume", "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_89ffc7f190094e568bb47dc3666592de", "page_model": { "artifacts": { "artifact_slug": "openlit", "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 openlit", "label": "Python / pip · 官方安装入口", "source": "https://github.com/openlit/openlit#readme", "verified": true } ], "display_tags": [ "MCP 工具", "知识库问答", "流程自动化", "断点恢复流程", "评测体系" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 local_cli的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "Open source platform for AI Engineering: OpenTelemetry-native LLM Observability, GPU Monitoring, Guardrails, Evaluations, Prompt Management, Vault, Playground. 🚀💻 Integrates with 50+ LLM Providers, VectorDBs, Agent Frameworks and GPUs." }, { "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": "prompt, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Integration: Governance and compliance signals for LLM observability", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_16e8a1979e4646f18ae6d36da1fd46fe | https://github.com/openlit/openlit/issues/1106 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Integration: Governance and compliance signals for LLM observability", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: gen_ai.agent.threat_detected span event helper for OTel-shaped detection observability", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_9788255c9fb34a7eae64ba6413a52030 | https://github.com/openlit/openlit/issues/1186 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Proposal: gen_ai.agent.threat_detected span event helper for OTel-shaped detection observability", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Docker Image doesn't run on windows 64bit", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_e25a08120daf4deb81b9193aeab1f929 | https://github.com/openlit/openlit/issues/786 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：[Bug]: Docker Image doesn't run on windows 64bit", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：openlit-1.19.0", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_0504e467960f4bbe919ff101c6a14d7b | https://github.com/openlit/openlit/releases/tag/openlit-1.19.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：openlit-1.19.0", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：controller-0.2.0", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_addec19eec37420da207487d5a685eaa | https://github.com/openlit/openlit/releases/tag/controller-0.2.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：controller-0.2.0", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：openlit-1.20.0", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_217968c917e9426f9f8fbb4b50bebdb5 | https://github.com/openlit/openlit/releases/tag/openlit-1.20.0 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：openlit-1.20.0", "user_impact": "可能影响升级、迁移或版本选择。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:747319327 | https://github.com/openlit/openlit | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:747319327 | https://github.com/openlit/openlit | 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:747319327 | https://github.com/openlit/openlit | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:747319327 | https://github.com/openlit/openlit | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Bug: OpenAI API key in operator example test-application is not using OPENAI_API_KEY env var", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_bfba0945570d4cbbaead1257e8f70dfe | https://github.com/openlit/openlit/issues/1135 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Bug: OpenAI API key in operator example test-application is not using OPENAI_API_KEY env var", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：openlit-1.19.1", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_b5088506959947828f2d740f9297d5b5 | https://github.com/openlit/openlit/releases/tag/openlit-1.19.1 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：openlit-1.19.1", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：py-1.41.2", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_ff3f4dfa2dc04616be73482b2145ac5c | https://github.com/openlit/openlit/releases/tag/py-1.41.2 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：py-1.41.2", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:747319327 | https://github.com/openlit/openlit | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" }, { "body": "release_recency=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:747319327 | https://github.com/openlit/openlit | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Integration: Governance and compliance signals for LLM observability。", "title": "踩坑日志" }, "snapshot": { "contributors": 69, "forks": 276, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 2446 }, "source_url": "https://github.com/openlit/openlit", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "Open source platform for AI Engineering: OpenTelemetry-native LLM Observability, GPU Monitoring, Guardrails, Evaluations, Prompt Management, Vault, Playground. 🚀💻 Integrates with 50+ LLM Providers, VectorDBs, Agent Frameworks and GPUs.", "title": "openlit 能力包", "trial_prompt": "# openlit - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 openlit 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Open source platform for AI Engineering: OpenTelemetry-native LLM Observability, GPU Monitoring, Guardrails, Evaluations, Prompt Management, Vault, Playground. 🚀💻 Integrates with 50+ LLM Providers, VectorDBs, Agent Frameworks and GPUs. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. python-sdk：Python SDK。围绕“Python SDK”模拟一次用户任务，不展示安装或运行结果。\n4. observability：可观测性功能。围绕“可观测性功能”模拟一次用户任务，不展示安装或运行结果。\n5. evaluations：评估功能。围绕“评估功能”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. python-sdk\n输入：用户提供的“Python SDK”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. observability\n输入：用户提供的“可观测性功能”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. evaluations\n输入：用户提供的“评估功能”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / system-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / python-sdk：Step 3 必须围绕“Python SDK”形成一个小中间产物，并等待用户确认。\n- Step 4 / observability：Step 4 必须围绕“可观测性功能”形成一个小中间产物，并等待用户确认。\n- Step 5 / evaluations：Step 5 必须围绕“评估功能”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/openlit/openlit\n- https://github.com/openlit/openlit#readme\n- README.md\n- docker-compose.yml\n- src/dev-docker-compose.yml\n- src/client/prisma/schema.prisma\n- sdk/python/src/openlit/__init__.py\n- sdk/python/src/openlit/_instrumentors.py\n- sdk/python/pyproject.toml\n- sdk/python/src/openlit/otel/tracing.py\n- sdk/python/src/openlit/otel/metrics.py\n- sdk/python/src/openlit/otel/events.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 openlit 的核心服务。\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: Proposal: gen_ai.agent.threat_detected span event helper for OTel-shaped（https://github.com/openlit/openlit/issues/1186）；github/github_issue: [Bug]: Docker Image doesn't run on windows 64bit（https://github.com/openlit/openlit/issues/786）；github/github_issue: Bug: OpenAI API key in operator example test-application is not using OP（https://github.com/openlit/openlit/issues/1135）；github/github_issue: Integration: Governance and compliance signals for LLM observability（https://github.com/openlit/openlit/issues/1106）；github/github_release: openlit-1.20.0（https://github.com/openlit/openlit/releases/tag/openlit-1.20.0）；github/github_release: controller-0.2.0（https://github.com/openlit/openlit/releases/tag/controller-0.2.0）；github/github_release: openlit-1.19.1（https://github.com/openlit/openlit/releases/tag/openlit-1.19.1）；github/github_release: controller-0.1.0（https://github.com/openlit/openlit/releases/tag/controller-0.1.0）；github/github_release: openlit-1.19.0（https://github.com/openlit/openlit/releases/tag/openlit-1.19.0）；github/github_release: py-1.41.2（https://github.com/openlit/openlit/releases/tag/py-1.41.2）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "Proposal: gen_ai.agent.threat_detected span event helper for OTel-shaped", "url": "https://github.com/openlit/openlit/issues/1186" }, { "kind": "github_issue", "source": "github", "title": "[Bug]: Docker Image doesn't run on windows 64bit", "url": "https://github.com/openlit/openlit/issues/786" }, { "kind": "github_issue", "source": "github", "title": "Bug: OpenAI API key in operator example test-application is not using OP", "url": "https://github.com/openlit/openlit/issues/1135" }, { "kind": "github_issue", "source": "github", "title": "Integration: Governance and compliance signals for LLM observability", "url": "https://github.com/openlit/openlit/issues/1106" }, { "kind": "github_release", "source": "github", "title": "openlit-1.20.0", "url": "https://github.com/openlit/openlit/releases/tag/openlit-1.20.0" }, { "kind": "github_release", "source": "github", "title": "controller-0.2.0", "url": "https://github.com/openlit/openlit/releases/tag/controller-0.2.0" }, { "kind": "github_release", "source": "github", "title": "openlit-1.19.1", "url": "https://github.com/openlit/openlit/releases/tag/openlit-1.19.1" }, { "kind": "github_release", "source": "github", "title": "controller-0.1.0", "url": "https://github.com/openlit/openlit/releases/tag/controller-0.1.0" }, { "kind": "github_release", "source": "github", "title": "openlit-1.19.0", "url": "https://github.com/openlit/openlit/releases/tag/openlit-1.19.0" }, { "kind": "github_release", "source": "github", "title": "py-1.41.2", "url": "https://github.com/openlit/openlit/releases/tag/py-1.41.2" } ], "status": "已收录 10 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "Open source platform for AI Engineering: OpenTelemetry-native LLM Observability, GPU Monitoring, Guardrails, Evaluations, Prompt Management, Vault, Playground. 🚀💻 Integrates with 50+ LLM Providers, VectorDBs, Agent Frameworks and GPUs.", "effort": "安装已验证", "forks": 276, "icon": "code", "name": "openlit 能力包", "risk": "可发布", "slug": "openlit", "stars": 2446, "tags": [ "MCP 工具", "知识库问答", "流程自动化", "断点恢复流程", "评测体系" ], "thumb": "gray", "type": "Prompt Preview" }, "manual": { "markdown": "# https://github.com/openlit/openlit 项目说明书\n\n生成时间：2026-05-16 21:10:55 UTC\n\n## 目录\n\n- [项目概述](#project-overview)\n- [系统架构](#system-architecture)\n- [Python SDK](#python-sdk)\n- [TypeScript SDK](#typescript-sdk)\n- [Go SDK](#go-sdk)\n- [可观测性功能](#observability)\n- [评估功能](#evaluations)\n- [Guardrails与规则引擎](#guardrails)\n- [OpenLIT Controller](#controller)\n- [GPU Collector](#gpu-collector)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [Python SDK](#python-sdk)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/client/src/app/(playground)/getting-started/page.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/app/(playground)/getting-started/page.tsx)\n- [src/client/src/components/(playground)/getting-started/tracing/index.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/components/(playground)/getting-started/tracing/index.tsx)\n- [src/client/src/components/(playground)/openground/sdk-usage-dialog.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/components/(playground)/openground/sdk-usage-dialog.tsx)\n- [src/client/src/app/(playground)/evaluations/types/new/page.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/app/(playground)/evaluations/types/new/page.tsx)\n- [src/client/src/components/(playground)/agents/version-drawer.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/components/(playground)/agents/version-drawer.tsx)\n- [src/client/src/app/(playground)/context/page.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/app/(playground)/context/page.tsx)\n- [src/client/src/components/(auth)/auth-form.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/components/(auth)/auth-form.tsx)\n- [src/client/src/app/(playground)/pricing/page.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/app/(playground)/pricing/page.tsx)\n
\n\n# 项目概述\n\n## 1. 项目简介\n\nOpenLIT 是一个基于 OpenTelemetry 原生设计的 **GenAI 和 LLM 应用程序可观测性工具**。它旨在简化将可观测性功能集成到 LLM 应用中的过程，使开发者能够轻松地收集、监控和分析 AI 应用产生的追踪数据和指标数据。\n\n资料来源：[src/client/src/app/(playground)/getting-started/page.tsx:130-132]()\n\n### 1.1 核心定位\n\nOpenLIT 的主要目标是为 GenAI 和 LLM 应用程序提供全面的可观测性支持。通过集成 OpenTelemetry 标准，OpenLIT 能够：\n\n- 自动收集 AI 应用中的追踪数据（Traces）\n- 采集关键性能指标（Metrics）\n- 提供可视化的监控仪表板\n- 支持多语言 SDK（Python、TypeScript）\n\n资料来源：[src/client/src/app/(playground)/getting-started/page.tsx:131-133]()\n\n### 1.2 技术架构\n\nOpenLIT 采用现代化的微服务架构设计，核心组件包括：\n\n| 组件 | 功能描述 | 技术栈 |\n|------|---------|--------|\n| 前端界面 | 提供可视化监控和配置界面 | React/Next.js |\n| 后端服务 | 处理数据存储和 API 请求 | Node.js/Go |\n| OpenTelemetry 接收器 | 接收并处理 OTLP 数据 | OpenTelemetry SDK |\n| 数据库 | 存储追踪和指标数据 | PostgreSQL/TimescaleDB |\n\n资料来源：[src/client/src/app/(playground)/getting-started/page.tsx:135-140]()\n\n## 2. 快速部署\n\n### 2.1 Docker Compose 部署\n\nOpenLIT 支持通过 Docker Compose 进行快速部署，适合本地开发和测试环境。\n\n```bash\n# 克隆仓库\ngit clone git@github.com:openlit/openlit.git\n\n# 启动服务\ncd openlit\ndocker compose up -d\n```\n\n资料来源：[src/client/src/app/(playground)/getting-started/page.tsx:145-150]()\n\n### 2.2 服务访问\n\n部署完成后，通过以下地址访问 OpenLIT：\n\n- **访问地址**：http://127.0.0.1:3000\n- **OTLP 端点**：http://127.0.0.1:4318\n\n默认登录凭证：\n\n| 字段 | 默认值 |\n|------|--------|\n| 邮箱 | user@openlit.io |\n| 密码 | openlituser |\n\n资料来源：[src/client/src/app/(playground)/getting-started/page.tsx:127-130]()\n\n## 3. SDK 集成\n\nOpenLIT 提供多语言 SDK，支持在不同技术栈中快速集成可观测性功能。\n\n### 3.1 Python SDK\n\n```python\nimport openlit\n\nopenlit.init(otlp_endpoint=\"http://127.0.0.1:4318\")\n```\n\n安装命令：\n\n```bash\npip install openlit\n```\n\n资料来源：[src/client/src/app/(playground)/getting-started/page.tsx:165-175]()\n\n### 3.2 TypeScript SDK\n\n```typescript\nimport openlit from 'openlit';\n\nopenlit.init({\n otlpEndpoint: \"http://127.0.0.1:4318\"\n});\n```\n\n安装命令：\n\n```bash\nnpm install openlit\n```\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:85-95]()\n\n### 3.3 环境变量配置\n\n除代码配置外，也可通过环境变量设置 OTLP 端点：\n\n```bash\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"http://127.0.0.1:4318\"\n```\n\n资料来源：[src/client/src/app/(playground)/getting-started/page.tsx:178-180]()\n\n## 4. 核心功能模块\n\n### 4.1 追踪功能（Tracing）\n\nOpenLIT 的追踪模块提供对 AI 应用请求链路的完整可视化。通过追踪，开发者可以：\n\n- 查看完整的请求调用链路\n- 分析各环节的延迟和性能\n- 识别潜在的性能瓶颈\n- 追踪 prompt 和响应内容\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:1-10]()\n\n### 4.2 评估功能（Evaluations）\n\n评估模块允许用户创建和管理自定义评估类型，用于衡量 AI 应用输出的质量：\n\n| 字段 | 说明 |\n|------|------|\n| 名称 | 评估类型的标识名称 |\n| 描述 | 评估目的和使用场景的说明 |\n| 评估 Prompt | LLM 评判使用的提示词模板 |\n\n资料来源：[src/client/src/app/(playground)/evaluations/types/new/page.tsx:1-25]()\n\n### 4.3 上下文管理（Context）\n\n上下文管理功能用于存储和管理 AI 应用中的共享上下文数据，包括：\n\n- 上下文描述\n- 状态管理（ACTIVE/INACTIVE）\n- 创建者和创建时间\n- 版本控制\n\n资料来源：[src/client/src/app/(playground)/context/page.tsx:1-25]()\n\n### 4.4 代理管理（Agents）\n\n代理模块追踪和展示 AI 代理的行为信息：\n\n| 属性 | 说明 |\n|------|------|\n| first_seen | 首次发现时间 |\n| last_seen | 最后活动 时间 |\n| request_count | 请求计数 |\n| primary_model | 主要使用的模型 |\n\n资料来源：[src/client/src/components/(playground)/agents/version-drawer.tsx:1-15]()\n\n## 5. 认证与授权\n\nOpenLIT 支持多种认证方式：\n\n| 认证方式 | 描述 |\n|---------|------|\n| Google OAuth | 通过 Google 账户登录 |\n| GitHub OAuth | 通过 GitHub 账户登录 |\n| 邮箱密码 | 本地账户密码认证 |\n\n资料来源：[src/client/src/components/(auth)/auth-form.tsx:1-20]()\n\n## 6. 数据流向架构\n\n```mermaid\ngraph TD\n A[AI Application] -->|SDK Instrumentation| B[OpenLIT SDK]\n B -->|OTLP Protocol| C[OTLP Endpoint :4318]\n C -->|Traces & Metrics| D[OpenLIT Backend]\n D -->|Storage| E[(Database)]\n D -->|Query| F[Frontend Dashboard :3000]\n G[User] -->|Authentication| H[Auth Provider]\n H -->|Session| F\n```\n\n资料来源：[src/client/src/app/(playground)/getting-started/page.tsx:127-145]()\n\n## 7. 定价模式\n\nOpenLIT 支持灵活的计费模式，包括自动计费功能。系统按以下流程运作：\n\n1. 用户配置使用计划\n2. 系统自动监控使用量\n3. 实时更新计费信息\n4. 支持多种支付方式\n\n资料来源：[src/client/src/app/(playground)/pricing/page.tsx:1-20]()\n\n## 8. SDK 使用示例\n\n### 8.1 Python 与 OpenAI 集成\n\n```python\nimport openlit\nfrom openai import OpenAI\n\nopenlit.init(otlp_endpoint=\"http://127.0.0.1:4318\")\n\nclient = OpenAI(api_key=os.environ.get(\"OPENAI_API_KEY\"))\n\nresponse = client.chat.completions.create(\n model=\"gpt-3.5-turbo\",\n messages=[{\"role\": \"user\", \"content\": \"What is LLM Observability?\"}]\n)\n```\n\n### 8.2 TypeScript 与 OpenAI 集成\n\n```typescript\nimport OpenAI from 'openai';\nimport openlit from 'openlit';\n\nopenlit.init({ otlpEndpoint: \"http://127.0.0.1:4318\" });\n\nconst client = new OpenAI({\n apiKey: process.env.OPENAI_API_KEY\n});\n\nconst chatCompletion = await client.chat.completions.create({\n messages: [{ role: 'user', content: 'What is LLM Observability?' }],\n model: 'gpt-3.5-turbo',\n});\n```\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:95-115]()\n\n## 9. 项目结构\n\n```\nopenlit/\n├── sdk/\n│ ├── python/ # Python SDK\n│ └── typescript/ # TypeScript SDK\n├── src/\n│ └── client/ # 前端应用\n│ └── src/\n│ ├── app/ # Next.js 应用页面\n│ ├── components/ # React 组件\n│ └── lib/ # 工具库\n├── docker-compose.yml # Docker 编排配置\n└── README.md # 项目说明文档\n```\n\n## 10. 总结\n\nOpenLIT 作为一个开源的 LLM 可观测性平台，通过以下优势为 AI 开发者提供价值：\n\n- **OpenTelemetry 原生**：遵循行业标准，便于与现有监控体系集成\n- **多语言支持**：提供 Python 和 TypeScript SDK，覆盖主流 AI 开发场景\n- **快速部署**：支持 Docker Compose 一键部署\n- **开箱即用**：提供完整的监控面板和可视化界面\n\n开发者可以通过访问官方文档 https://docs.openlit.io 获取更多信息和技术支持。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#project-overview), [Python SDK](#python-sdk), [OpenLIT Controller](#controller)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/client/src/components/(playground)/getting-started/tracing/index.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/components/(playground)/getting-started/tracing/index.tsx)\n- [src/client/src/app/(playground)/agents/no-controller.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/app/(playground)/agents/no-controller.tsx)\n- [src/client/src/app/(playground)/getting-started/page.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/app/(playground)/getting-started/page.tsx)\n- [src/client/src/components/(playground)/agents/observability-block.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/components/(playground)/agents/observability-block.tsx)\n- [src/client/src/app/(playground)/agents/controller/[instance_id]/page.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/app/(playground)/agents/controller/[instance_id]/page.tsx)\n- [src/client/README.md](https://github.com/openlit/openlit/blob/main/src/client/README.md)\n
\n\n# 系统架构\n\n## 概述\n\nOpenLIT 是一个基于 OpenTelemetry 原生设计的 **GenAI 和 LLM 应用可观测性平台**。平台通过采集、传输和处理来自 LLM 应用的遥测数据（Traces 和 Metrics），为开发者提供全面的 AI 应用监控能力。资料来源：[src/client/README.md:1]()\n\n## 核心设计理念\n\nOpenLIT 的架构遵循以下核心原则：\n\n| 原则 | 说明 |\n|------|------|\n| OpenTelemetry 原生 | 完全兼容 OpenTelemetry 标准协议和 SDK |\n| 无侵入集成 | 通过 SDK 初始化即可完成自动埋点 |\n| 多语言支持 | 提供 Python 和 TypeScript 双语言 SDK |\n| 灵活部署 | 支持 Linux、Docker 和 Kubernetes 多种部署方式 |\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:42-60]()\n\n## 系统组件架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph \"LLM 应用层\"\n A[Python SDK] \n B[TypeScript SDK]\n end\n \n subgraph \"数据采集层\"\n C[OpenTelemetry Collector]\n end\n \n subgraph \"OpenLIT 平台层\"\n D[前端界面]\n E[后端服务]\n F[数据库]\n end\n \n A --> C\n B --> C\n C --> E\n E --> F\n E --> D\n```\n\n### SDK 层\n\nOpenLIT 提供两种语言的 SDK 用于在应用中埋点：\n\n#### Python SDK\n\n```python\nimport openlit\n\nopenlit.init(otlp_endpoint=\"http://127.0.0.1:4318\")\n```\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:70-75]()\n\n#### TypeScript SDK\n\n```typescript\nimport openlit from 'openlit';\n\nopenlit.init({\n otlpEndpoint: \"http://127.0.0.1:4318\"\n});\n```\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:48-54]()\n\n### 数据流向\n\n```mermaid\ngraph LR\n A[LLM 应用] -->|OTLP Protocol| B[OTEL Collector]\n B -->|Traces| C[OpenLIT Backend]\n B -->|Metrics| C\n C -->|存储| D[(Database)]\n D -->|查询| E[Web UI]\n```\n\n## 部署架构\n\nOpenLIT 支持三种主要的部署模式，适用于不同的基础设施环境。\n\n### Linux 系统部署\n\n适用于直接在 Linux 主机上运行监控代理的场景。使用 systemd 管理服务生命周期：\n\n```bash\ncat < B[Getting Started]\n A --> C[Agents]\n A --> D[Context]\n \n C --> C1[Controller Instance]\n C --> C2[Tools]\n \n D --> D1[New Context]\n D --> D2[Context Detail]\n```\n\n### 技术栈\n\nOpenLIT 前端基于 Next.js 框架构建，使用以下核心组件库：\n\n| 组件 | 用途 |\n|------|------|\n| `Tabs` | 语言/模式切换 |\n| `Card` | 内容区块展示 |\n| `Accordion` | 可折叠面板 |\n| `CodeBlock` | 代码高亮显示 |\n| `Dialog` | 模态对话框 |\n\n资料来源：[src/client/src/app/(playground)/getting-started/page.tsx:80-95]()\n\n### 主题支持\n\n平台支持亮色和暗色主题，通过 Tailwind CSS 的 dark mode 类实现：\n\n| 主题 | 类名前缀 |\n|------|----------|\n| 亮色 | 默认 |\n| 暗色 | `dark:` |\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:5-6]()\n\n## 接入流程\n\n### 快速接入步骤\n\n```mermaid\ngraph LR\n A[安装 SDK] --> B[初始化配置]\n B --> C[设置 OTLP Endpoint]\n C --> D[启动应用]\n D --> E[查看监控数据]\n```\n\n### 环境变量配置\n\n除了代码初始化外，还可以通过环境变量配置端点：\n\n```bash\nOTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318\n```\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:6-8]()\n\n## 上下文管理\n\nOpenLIT 提供上下文（Context）管理功能，允许用户创建和管理监控上下文：\n\n| 功能 | 说明 |\n|------|------|\n| 创建上下文 | 支持描述和 Markdown 内容 |\n| 编辑上下文 | 提供 Write/Preview 双模式 |\n| 关联规则 | 可为上下文绑定业务规则 |\n\n资料来源：[src/client/src/app/(playground)/context/[id]/page.tsx:45-55]()\n\n## 版本管理\n\n控制器实例支持版本历史追踪，每个版本记录：\n\n| 属性 | 说明 |\n|------|------|\n| `first_seen` | 首次发现时间 |\n| `last_seen` | 最后活跃时间 |\n| `request_count` | 请求计数 |\n| `primary_model` | 主要使用的 LLM 模型 |\n\n资料来源：[src/client/src/components/(playground)/agents/version-drawer.tsx:10-20]()\n\n## 安全配置\n\n### API Key 认证\n\n在生产环境中部署时，可通过 API Key 进行认证：\n\n```bash\nhelm upgrade --install openlit openlit/openlit \\\n --set openlit-controller.apiKey=\"${apiKey}\"\n```\n\n资料来源：[src/client/src/app/(playground)/agents/no-controller.tsx:42-45]()\n\n## 默认凭证\n\n平台提供默认登录凭证供初次使用：\n\n| 字段 | 值 |\n|------|-----|\n| 访问地址 | `http://127.0.0.1:3000` |\n| 邮箱 | `user@openlit.io` |\n| 密码 | `openlituser` |\n\n资料来源：[src/client/src/app/(playground)/getting-started/page.tsx:45-48]()\n\n## 总结\n\nOpenLIT 采用现代化的微服务架构设计，通过 OpenTelemetry 标准协议实现与各类 LLM 框架的无缝集成。平台提供了从 SDK 埋点到数据可视化展示的完整链路，支持灵活的部署方式和多种运行环境，能够满足从开发测试到生产部署的不同场景需求。\n\n---\n\n\n\n## Python SDK\n\n### 相关页面\n\n相关主题：[TypeScript SDK](#typescript-sdk), [Go SDK](#go-sdk), [可观测性功能](#observability)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [sdk/python/src/openlit/instrumentation/claude_agent_sdk/__init__.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/instrumentation/claude_agent_sdk/__init__.py)\n- [sdk/python/src/openlit/instrumentation/claude_agent_sdk/claude_agent_sdk.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/instrumentation/claude_agent_sdk/claude_agent_sdk.py)\n- [sdk/python/src/openlit/guard/__init__.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/guard/__init__.py)\n- [sdk/python/src/openlit/__helpers.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/__helpers.py)\n- [sdk/python/src/openlit/instrumentation/agent_framework/utils.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/instrumentation/agent_framework/utils.py)\n- [sdk/python/src/openlit/instrumentation/google_adk/utils.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/instrumentation/google_adk/utils.py)\n
\n\n# Python SDK\n\nOpenLIT Python SDK 是一个基于 OpenTelemetry 原生的 GenAI 和 LLM 应用可观测性工具。它通过自动插桩主流 AI 框架和模型提供商，自动捕获追踪（traces）、指标（metrics）和日志，帮助开发者实现对 AI 应用的深度可视化监控。\n\n## 核心架构\n\nOpenLIT Python SDK 的架构围绕三个主要模块展开：\n\n```mermaid\ngraph TD\n A[用户应用代码] --> B[OpenLIT Python SDK]\n B --> C[插桩模块 Instrumentation]\n B --> D[防护模块 Guardrails]\n B --> E[辅助工具 Helpers]\n \n C --> C1[Claude Agent SDK]\n C --> C2[Google ADK]\n C --> C3[Agent Framework]\n C --> C4[LangGraph]\n C --> C5[CrewAI]\n \n D --> D1[PII 检测]\n D --> D2[提示注入检测]\n D --> D3[敏感话题检测]\n D --> D4[内容审核]\n D --> D5[主题限制]\n \n E --> E1[工具定义构建]\n E --> E2[系统指令构建]\n E --> E3[自定义属性应用]\n```\n\n## 快速开始\n\n### 安装\n\n```bash\npip install openlit\n```\n\n### 初始化\n\n在应用代码中添加以下两行：\n\n```python\nimport openlit\n\nopenlit.init(otlp_endpoint=\"http://127.0.0.1:4318\")\n```\n\n### 与 OpenAI 配合使用\n\n```python\nfrom openai import OpenAI\nimport openlit\n\nopenlit.init(otlp_endpoint=\"http://127.0.0.1:4318\")\n\nclient = OpenAI(api_key=\"YOUR_OPENAI_KEY\")\n\nchat_completion = client.chat.completions.create(\n messages=[\n {\n \"role\": \"user\",\n \"content\": \"What is LLM Observability?\",\n }\n ],\n model=\"gpt-3.5-turbo\",\n)\n```\n\n## 插桩模块（Instrumentation）\n\n插桩模块是 SDK 的核心，负责自动捕获 AI 框架调用并生成符合 OTel GenAI 语义约定的追踪数据。\n\n### 支持的框架\n\n| 框架 | 版本要求 | 功能 |\n|------|----------|------|\n| Claude Agent SDK | >= 0.1.0 | `invoke_agent` 和 `execute_tool` span |\n| Google ADK | - | 工具执行追踪 |\n| Agent Framework | - | Agent 和工作流追踪 |\n| LangGraph | - | 图执行追踪 |\n| CrewAI | - | Agent 和任务追踪 |\n\n### Claude Agent SDK 插桩\n\nClaude Agent SDK 插桩模块实现了对 `query()` 方法和 `ClaudeSDKClient` 的包装，生成 `invoke_agent` 和 `execute_tool` 两种 span 类型。\n\n```python\nfrom openlit.instrumentation.claude_agent_sdk import ClaudeAgentSDKInstrumentor\n\n# 启用插桩\nClaudeAgentSDKInstrumentor().instrument()\n```\n\n插桩模块通过 SDK 的 Hook 系统（`PreToolUse` / `PostToolUse` / `PostToolUseFailure`）创建工具 span，并使用基于消息流的回退机制处理 Hook 无法注入的场景。\n\n资料来源：[sdk/python/src/openlit/instrumentation/claude_agent_sdk/__init__.py:1-35]()\n\n### Agent Framework 插桩\n\nAgent Framework 插桩提供标准化的 span 命名和操作类型映射：\n\n| 端点 | 操作类型 | Span 名称格式 |\n|------|----------|---------------|\n| `agent_init` | agent | `create_agent {name}` |\n| `agent_run` | agent | `invoke_agent {name}` |\n| `tool_execute` | tools | `execute_tool {name}` |\n| `workflow_run` | workflow | `invoke_workflow {name}` |\n\n```python\n# 工具执行 span 名称生成逻辑\ndef generate_span_name(endpoint, instance, args=None, kwargs=None):\n operation_type = get_operation_type(endpoint)\n \n if endpoint == \"agent_init\":\n name = getattr(instance, \"name\", None) or getattr(instance, \"id\", None) or \"agent\"\n return f\"create_agent {name}\"\n \n if endpoint == \"tool_execute\":\n name = getattr(instance, \"name\", None) or type(instance).__name__\n return f\"execute_tool {name}\"\n```\n\n资料来源：[sdk/python/src/openlit/instrumentation/agent_framework/utils.py:1-70]()\n\n### Google ADK 插桩\n\nGoogle ADK 插桩为工具调用添加 OTel GenAI 语义约定属性：\n\n```python\nspan.set_attribute(SemanticConvention.GEN_AI_OPERATION, \n SemanticConvention.GEN_AI_OPERATION_TYPE_TOOLS)\nspan.set_attribute(SemanticConvention.GEN_AI_PROVIDER_NAME,\n SemanticConvention.GEN_AI_SYSTEM_GOOGLE_ADK)\n```\n\n资料来源：[sdk/python/src/openlit/instrumentation/google_adk/utils.py:1-50]()\n\n## 防护模块（Guardrails）\n\nOpenLIT 提供了生产级的 LLM 应用防护栏功能，用于过滤和验证输入输出内容。\n\n### 可用防护类型\n\n| 防护类型 | 功能说明 |\n|----------|----------|\n| `PII` | 检测并处理个人身份信息 |\n| `PromptInjection` | 检测提示注入攻击 |\n| `SensitiveTopic` | 检测敏感话题内容 |\n| `TopicRestriction` | 限制允许的话题范围 |\n| `Moderation` | 内容审核 |\n| `Schema` | 输出结构验证 |\n| `Custom` | 自定义防护规则 |\n\n### 使用方法\n\n防护类可以直接在 `openlit.init()` 中配置：\n\n```python\nimport openlit\n\nopenlit.init(\n otlp_endpoint=\"http://127.0.0.1:4318\",\n guards=[openlit.PII(action=\"redact\")]\n)\n```\n\n或者直接导入使用：\n\n```python\nfrom openlit import PII, PromptInjection, Moderation\n\n# 单独使用\npii_guard = PII(action=\"redact\")\nresult = pii_guard.check(user_input)\n```\n\n### 核心类结构\n\n| 类名 | 说明 |\n|------|------|\n| `Guard` | 防护基类 |\n| `GuardAction` | 防护动作枚举 |\n| `GuardConfigError` | 配置错误异常 |\n| `GuardDeniedError` | 防护拒绝异常 |\n| `GuardPhase` | 执行阶段枚举 |\n| `GuardResult` | 防护结果数据类 |\n| `GuardTimeoutError` | 超时异常 |\n| `PipelineResult` | 管道执行结果 |\n\n资料来源：[sdk/python/src/openlit/guard/__init__.py:1-55]()\n\n## 辅助工具（Helpers）\n\n`__helpers.py` 模块提供通用的辅助函数，用于处理 AI 请求中的常见数据结构。\n\n### 构建工具定义\n\n`build_tool_definitions()` 函数从聊天请求的 `tools` 参数中提取工具/函数定义：\n\n```python\ndef build_tool_definitions(tools):\n \"\"\"\n 支持两种模式：\n 1. OpenAI 风格: {\"type\": \"function\", \"function\": {...}}\n 2. 扁平模式: {\"name\": ..., \"description\": ..., \"parameters\": ...}\n \"\"\"\n```\n\n返回值格式：\n\n```python\n{\n \"type\": \"function\",\n \"name\": str,\n \"description\": str,\n \"parameters\": dict\n}\n```\n\n### 构建系统指令\n\n`build_system_instructions()` 函数从各种格式中提取系统指令：\n\n```python\ninstructions = [\n {\"type\": \"text\", \"content\": str(content)},\n {\"type\": \"resource\", \"uri\": str(uri), \"content\": str(content)}\n]\n```\n\n### 异常处理\n\n`handle_exception()` 函数用于统一处理插桩过程中的异常，确保不影响主业务流程。\n\n资料来源：[sdk/python/src/openlit/__helpers.py:1-100]()\n\n## 配置选项\n\n### 初始化参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `otlp_endpoint` | str | 环境变量 | OTLP 接收端点 |\n| `application_name` | str | \"default\" | 应用名称 |\n| `environment` | str | \"default\" | 环境名称 |\n| `pricing_info` | dict | {} | 价格信息映射 |\n| `capture_message_content` | bool | False | 是否捕获消息内容 |\n| `disable_metrics` | bool | None | 是否禁用指标 |\n| `guards` | list | [] | 防护配置列表 |\n\n### 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP 接收端点 |\n| `OTEL_SERVICE_NAME` | 服务名称 |\n\n## 追踪数据模型\n\n### Span 类型与属性\n\nOpenLIT 使用 OTel GenAI 语义约定定义 span 属性：\n\n| 属性键 | 值 | 适用 Span |\n|--------|-----|-----------|\n| `gen_ai.operation.name` | `agent` / `tools` / `workflow` | Agent 调用 |\n| `gen_ai.operation.type` | `create` / `invoke` | 操作类型 |\n| `gen_ai.system` | `openai` / `anthropic` 等 | AI 系统 |\n| `gen_ai.tool.name` | 工具名称 | 工具调用 |\n| `gen_ai.tool.type` | `function` 等 | 工具类型 |\n| `gen_ai.tool.call.arguments` | 调用参数 | 工具调用 |\n| `gen_ai.tool.call.id` | 调用 ID | 工具调用 |\n| `gen_ai.response.id` | 响应 ID | 模型响应 |\n| `gen_ai.prompt.token_count` | 提示 token 数 | 请求 |\n| `gen_ai.completion.token_count` | 完成 token 数 | 响应 |\n\n### SpanKind 映射\n\n| 操作类型 | SpanKind |\n|----------|----------|\n| `agent` | `CLIENT` |\n| `tools` | `INTERNAL` |\n| `workflow` | `INTERNAL` |\n\n## 工作流程\n\n### 自动插桩流程\n\n```mermaid\nsequenceDiagram\n participant App as 应用代码\n participant Inst as 插桩器\n participant SDK as AI SDK\n participant OTel as OpenTelemetry\n \n App->>Inst: instrument()\n Inst->>SDK: 包装目标函数\n App->>SDK: 调用 AI 方法\n SDK->>Inst: 触发包装函数\n Inst->>OTel: 创建 Span\n Inst->>Inst: 提取模型/工具信息\n Inst->>OTel: 设置语义属性\n SDK-->>App: 返回结果\n Inst->>OTel: 结束 Span\n```\n\n### 防护检查流程\n\n```mermaid\ngraph LR\n A[用户输入] --> B{PII 检测}\n B -->|通过| C{提示注入检测}\n B -->|发现 PII| D[处理/拒绝]\n C -->|通过| E{内容审核}\n C -->|检测到注入| F[拒绝]\n E -->|通过| G[发送给 LLM]\n E -->|违规| H[拒绝]\n```\n\n## 与 TypeScript SDK 的对比\n\n| 特性 | Python SDK | TypeScript SDK |\n|------|------------|----------------|\n| 安装命令 | `pip install openlit` | `npm install openlit` |\n| 初始化语法 | `openlit.init(otlp_endpoint=\"...\")` | `openlit.init({ otlpEndpoint: \"...\" })` |\n| 插桩方式 | 自动包装函数 | 自动包装函数 |\n| 防护模块 | 完整支持 | 完整支持 |\n\n## 下一步\n\n- 访问 [OpenLIT 官方文档](https://docs.openlit.io) 获取更多详细信息\n- 查看 [GitHub 仓库](https://github.com/openlit/openlit) 获取最新更新\n- 加入 [Slack 社区](https://join.slack.com/t/openlit/shared_invite/zt-2etnfttwg-TjP_7BZXfYg84oAukY8QRQ) 参与讨论\n\n---\n\n\n\n## TypeScript SDK\n\n### 相关页面\n\n相关主题：[Python SDK](#python-sdk), [Go SDK](#go-sdk)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/client/src/components/(playground)/getting-started/tracing/index.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/components/(playground)/getting-started/tracing/index.tsx)\n- [src/client/src/app/(playground)/getting-started/page.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/app/(playground)/getting-started/page.tsx)\n- [src/client/src/components/(playground)/openground/sdk-usage-dialog.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/components/(playground)/openground/sdk-usage-dialog.tsx)\n- [src/client/src/components/(playground)/agents/observability-block.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/components/(playground)/agents/observability-block.tsx)\n- [src/client/src/components/(playground)/agents/tools-card.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/components/(playground)/agents/tools-card.tsx)\n
\n\n# TypeScript SDK\n\n## 概述\n\nOpenLIT TypeScript SDK 是一个用于为 GenAI 和 LLM 应用程序添加可观测性的客户端库。它基于 OpenTelemetry 标准设计，能够自动捕获 LLM 调用、追踪请求链路、收集指标数据，并将其发送至 OpenLIT 后端进行可视化分析。\n\nSDK 通过简单的初始化配置即可集成到现有的 TypeScript/Node.js 应用中，支持与 OpenAI 等主流 LLM 提供商的自动集成。\n\n资料来源：[src/client/src/app/(playground)/getting-started/page.tsx:1-50]()\n\n## 核心功能\n\n### 自动插桩\n\nSDK 提供开箱即用的自动插桩功能，能够拦截并追踪 LLM API 调用。主要支持以下功能：\n\n| 功能 | 说明 |\n|------|------|\n| 请求捕获 | 自动捕获发送给 LLM 的所有请求 |\n| 响应记录 | 记录 LLM 返回的完整响应 |\n| Token 统计 | 统计输入/输出 Token 数量 |\n| 延迟追踪 | 测量请求处理耗时 |\n| 错误捕获 | 记录请求过程中发生的错误 |\n\n### 环境变量配置\n\n除代码配置外，SDK 还支持通过环境变量进行配置：\n\n```bash\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"http://127.0.0.1:4318\"\n```\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:80-85]()\n\n## 安装与快速开始\n\n### 安装 SDK\n\n使用 npm 安装 OpenLIT SDK：\n\n```bash\nnpm install openlit\n```\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:25-30]()\n\n### 初始化配置\n\n在应用入口处初始化 SDK：\n\n```typescript\nimport openlit from 'openlit';\n\nopenlit.init({\n otlpEndpoint: \"http://127.0.0.1:4318\"\n});\n```\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:35-42]()\n\n### OpenAI 集成示例\n\nSDK 与 OpenAI API 完美集成：\n\n```typescript\nimport OpenAI from 'openai';\nimport openlit from 'openlit';\n\nopenlit.init({ otlpEndpoint: \"http://127.0.0.1:4318\" });\n\nconst client = new OpenAI({\n apiKey: process.env.OPENAI_API_KEY\n});\n\nconst chatCompletion = await client.chat.completions.create({\n messages: [{ role: 'user', content: 'What is LLM Observability?' }],\n model: 'gpt-3.5-turbo',\n});\n```\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:55-70]()\n\n## 配置参数\n\n### init() 方法参数\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| otlpEndpoint | string | 否 | OTEL_EXPORTER_OTLP_ENDPOINT 环境变量 | OTLP 接收端点地址 |\n\n### 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| OTEL_EXPORTER_OTLP_ENDPOINT | OTLP exporter 的服务端点 |\n| OPENAI_API_KEY | OpenAI API 密钥（如使用 OpenAI） |\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:45-50]()\n\n## SDK 启用状态指示\n\n在 OpenLIT 前端界面中，已通过 SDK 接入的 Agent 会显示特定的标识状态：\n\n```typescript\n\n \n {getMessage().AGENTS_SDK_ENABLED_VIA}\n\n```\n\n资料来源：[src/client/src/components/(playground)/agents/observability-block.tsx:30-38]()\n\n### 状态标识说明\n\n| 状态 | 样式 | 含义 |\n|------|------|------|\n| SDK 已启用 | 绿色边框、绿色圆点 | 通过 OpenLIT SDK 进行追踪 |\n| 静态分析 | 绿色边框、绿色圆点 | 源代码已集成 SDK |\n| 等待确认 | 禁用按钮 | 等待 SDK 连接确认 |\n\n## 可观测性数据捕获\n\n### 工具定义捕获\n\nSDK 能够自动捕获 Agent 使用的工具定义和 schema：\n\n```typescript\n{tool.description && (\n

\n {tool.description}\n

\n)}\n{hasSchema(tool.schema) ? (\n
\n \n
\n) : (\n
\n {getMessage().AGENTS_DEFINITION_SCHEMA_NOT_CAPTURED}\n
\n)}\n```\n\n资料来源：[src/client/src/components/(playground)/agents/tools-card.tsx:20-35]()\n\n## 架构流程\n\n```mermaid\ngraph TD\n A[TypeScript 应用] --> B[OpenLIT SDK]\n B --> C[自动插桩层]\n C --> D[OpenAI API]\n D --> E[响应数据]\n C --> F[OTLP Exporter]\n F --> G[OpenLIT Collector]\n G --> H[数据存储]\n G --> I[前端可视化]\n \n J[环境变量配置] --> B\n K[otlpEndpoint 参数] --> B\n \n style A fill:#e1f5fe\n style D fill:#fff3e0\n style G fill:#e8f5e9\n style I fill:#f3e5f5\n```\n\n## 多语言 SDK 支持\n\nOpenLIT 提供多种语言的 SDK，TypeScript SDK 是其中之一：\n\n| SDK | 安装命令 | 初始化方式 |\n|-----|----------|------------|\n| Python | `pip install openlit` | `openlit.init(otlp_endpoint=\"...\")` |\n| TypeScript | `npm install openlit` | `openlit.init({ otlpEndpoint: \"...\" })` |\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:10-45]()\n\n## 使用场景\n\n### 场景一：LLM 应用监控\n\n在生产环境中部署 LLM 应用时，通过 SDK 实时监控：\n\n- API 调用频率和响应时间\n- Token 消耗统计\n- 错误率追踪\n\n### 场景二：Agent 行为分析\n\n结合 OpenLIT 的 Agent 可视化功能，分析：\n\n- 工具调用模式\n- 决策链路追踪\n- 上下文使用效率\n\n### 场景三：性能优化\n\n基于收集的遥测数据：\n\n- 识别性能瓶颈\n- 优化 Prompt 设计\n- 降低 API 成本\n\n## 高级配置\n\n### 异步初始化\n\nSDK 支持在异步环境中初始化：\n\n```typescript\nimport openlit from 'openlit';\n\nasync function initializeApp() {\n await openlit.init({\n otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT\n });\n}\n```\n\n### 条件初始化\n\n在开发环境中可选择性地禁用追踪：\n\n```typescript\nopenlit.init({\n otlpEndpoint: process.env.NODE_ENV === 'production' \n ? \"http://127.0.0.1:4318\" \n : undefined\n});\n```\n\n## 注意事项\n\n1. **端点配置优先级**：代码中的 `otlpEndpoint` 参数优先于环境变量\n2. **网络要求**：确保应用能够访问配置的 OTLP 端点\n3. **性能影响**：SDK 设计为低侵入性，对应用性能影响极小\n4. **数据类型**：自动捕获的数据包括文本内容，可能涉及敏感信息，请确保合规处理\n\n## 相关资源\n\n- 官方文档：https://docs.openlit.io\n- SDK 仓库：https://github.com/openlit/openlit/tree/main/sdk/typescript\n- OpenTelemetry 官方：https://opentelemetry.io\n\n---\n\n\n\n## Go SDK\n\n### 相关页面\n\n相关主题：[Python SDK](#python-sdk), [TypeScript SDK](#typescript-sdk)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [sdk/go/openlit.go](https://github.com/openlit/openlit/blob/main/sdk/go/openlit.go)\n- [sdk/go/config.go](https://github.com/openlit/openlit/blob/main/sdk/go/config.go)\n- [sdk/go/instrumentation/openai/instrumentor.go](https://github.com/openlit/openlit/blob/main/sdk/go/instrumentation/openai/instrumentor.go)\n- [sdk/go/instrumentation/anthropic/instrumentor.go](https://github.com/openlit/openlit/blob/main/sdk/go/instrumentation/anthropic/instrumentor.go)\n- [sdk/go/go.mod](https://github.com/openlit/openlit/blob/main/sdk/go/go.mod)\n- [sdk/go/README.md](https://github.com/openlit/openlit/blob/main/sdk/go/README.md)\n
\n\n# Go SDK\n\nOpenLIT Go SDK 是一个原生支持 OpenTelemetry 的观测工具，专为 Go 语言开发的 GenAI 应用和 LLM 应用设计。该 SDK 提供自动化的链路追踪（Tracing）和指标收集（Metrics）功能，使开发者能够轻松地将应用程序的观测数据导出至 OpenLIT 平台进行可视化和分析。\n\n## 核心架构\n\n```mermaid\ngraph TD\n A[Go 应用] --> B[OpenLIT SDK]\n B --> C[OpenAI Instrumentation]\n B --> D[Anthropic Instrumentation]\n C --> E[OpenTelemetry Collector]\n D --> E\n E --> F[OpenLIT Dashboard]\n \n G[Rule Engine] --> H[HTTP API 调用]\n H --> F\n```\n\nOpenLIT Go SDK 采用模块化架构，核心模块负责 SDK 初始化和配置管理，而插桩（Instrumentation）模块则负责拦截和追踪具体的 AI SDK 调用。Rule Engine 模块独立运行，无需调用 `Init()`，通过 HTTP 与 OpenLIT 平台通信。\n\n## 快速开始\n\n### 环境要求\n\n- Go 1.21 或更高版本\n- OpenLIT 后端服务运行中\n\n### 安装 SDK\n\n```bash\ngo get github.com/openlit/openlit/sdk/go\n```\n\n### 初始化 OpenLIT\n\n在应用程序启动时调用初始化方法：\n\n```go\npackage main\n\nimport (\n \"context\"\n \"log\"\n \n \"github.com/openlit/openlit/sdk/go\"\n)\n\nfunc main() {\n err := openlit.Init(openlit.Config{\n OtlpEndpoint: \"http://127.0.0.1:4318\",\n Environment: \"production\",\n ApplicationName: \"my-go-app\",\n })\n if err != nil {\n log.Fatalf(\"初始化 OpenLIT 失败: %v\", err)\n }\n defer openlit.Shutdown(context.Background())\n}\n```\n\n资料来源：[sdk/go/README.md:Quick Start]()\n\n## 配置选项\n\n`Config` 结构体是 SDK 的核心配置单元，支持多种自定义选项：\n\n| 配置项 | 类型 | 说明 | 默认值 |\n|--------|------|------|--------|\n| `OtlpEndpoint` | string | OTLP 导出端点地址 | `http://localhost:4318` |\n| `Environment` | string | 运行环境名称 | `\"default\"` |\n| `ApplicationName` | string | 应用名称 | `\"default\"` |\n| `PricingInfo` | `map[string]ModelPricing` | 自定义模型定价信息 | 空 |\n| `OtlpHeaders` | `map[string]string` | 自定义 OTLP 导出头 | 空 |\n\n### 自定义模型定价\n\n```go\nconfig := openlit.Config{\n PricingInfo: map[string]openlit.ModelPricing{\n \"gpt-4-custom\": {\n InputCostPerToken: 0.00003,\n OutputCostPerToken: 0.00006,\n },\n },\n}\n```\n\n资料来源：[sdk/go/README.md:Custom Pricing]()\n\n### 自定义 Headers\n\n```go\nconfig := openlit.Config{\n OtlpHeaders: map[string]string{\n \"Authorization\": \"Bearer token\",\n \"X-Custom-Header\": \"value\",\n },\n}\n```\n\n资料来源：[sdk/go/README.md:Custom Headers]()\n\n## OpenAI 插桩\n\nOpenAI 插桩模块提供了对 `sashabaranov/go-openai` 客户端的自动追踪支持。\n\n### 使用方式\n\n```go\nimport (\n \"github.com/openlit/openlit/sdk/go/instrumentation/openai\"\n openai_sdk \"github.com/sashabaranov/go-openai\"\n)\n\n// 创建并插桩 OpenAI 客户端\nclient := openai_sdk.NewClient(\"your-api-key\")\ninstrumentedClient := openai.Instrument(client)\n\n// 使用方式与普通客户端完全相同，自动产生追踪数据\nresp, err := instrumentedClient.CreateChatCompletion(ctx, openai_sdk.ChatCompletionRequest{\n Model: openai_sdk.GPT4,\n Messages: []openai_sdk.ChatCompletionMessage{\n {\n Role: openai_sdk.ChatMessageRoleUser,\n Content: \"Hello!\",\n },\n },\n})\n```\n\n资料来源：[sdk/go/README.md:Instrument OpenAI]()\n\n### 工作原理\n\n```mermaid\nsequenceDiagram\n participant App as 应用代码\n participant Inst as InstrumentedClient\n participant OpenAI as OpenAI API\n participant OTel as OpenTelemetry\n \n App->>Inst: CreateChatCompletion()\n Inst->>OpenAI: 调用 OpenAI API\n OpenAI-->>Inst: 返回响应\n Inst->>OTel: 创建 Span 和 Metrics\n Inst-->>App: 返回响应结果\n```\n\n插桩客户端内部自动拦截所有 API 调用，创建相应的 OpenTelemetry Span，并记录输入/输出 token 数量、成本等指标数据。\n\n## Anthropic 插桩\n\nAnthropic 插桩模块支持对 Anthropic Claude API 的追踪。\n\n### 使用方式\n\n```go\nimport (\n \"github.com/openlit/openlit/sdk/go/instrumentation/anthropic\"\n)\n\n// 创建并插桩 Anthropic 客户端\nclient := anthropic.NewClient(\"your-api-key\")\ninstrumentedClient := anthropic.Instrument(client)\n```\n\n资料来源：[sdk/go/README.md:Instrument Anthropic]()\n\n## 规则引擎\n\nOpenLIT Go SDK 提供独立的规则引擎评估功能，允许开发者对追踪属性进行规则匹配，并获取关联的实体信息。\n\n### 核心函数\n\n```go\nresult := openlit.EvaluateRule(ruleConfig)\n```\n\n### 特性\n\n- **独立运行**：无需调用 `openlit.Init()`，仅需 HTTP 连接即可使用\n- **规则匹配**：根据追踪属性评估匹配规则\n- **实体获取**：返回关联的上下文、提示词和评估配置\n\n资料来源：[sdk/go/README.md:Rule Engine]()\n\n## 与 OpenLIT Dashboard 集成\n\n### 1. 启动 OpenLIT 堆栈\n\n```bash\ndocker compose up -d\n```\n\n### 2. 配置 SDK 发送数据\n\n```go\nopenlit.Init(openlit.Config{\n OtlpEndpoint: \"http://localhost:4318\",\n})\n```\n\n### 3. 查看追踪数据\n\n访问 http://localhost:3000 查看可视化追踪和指标数据。\n\n资料来源：[sdk/go/README.md:Integration with OpenLIT Dashboard]()\n\n## 示例项目\n\nSDK 仓库包含完整的可运行示例：\n\n| 示例路径 | 说明 |\n|----------|------|\n| `examples/openai/chat/` | OpenAI 聊天补全示例 |\n| `examples/openai/streaming/` | OpenAI 流式响应示例 |\n| `examples/anthropic/messages/` | Anthropic 消息 API 示例 |\n| `examples/anthropic/streaming/` | Anthropic 流式响应示例 |\n\n资料来源：[sdk/go/README.md:Examples]()\n\n## 模块结构\n\n```\nsdk/go/\n├── openlit.go # 核心初始化和配置\n├── config.go # 配置结构体定义\n├── go.mod # 模块依赖声明\n├── instrumentation/\n│ ├── openai/\n│ │ └── instrumentor.go # OpenAI 插桩实现\n│ └── anthropic/\n│ └── instrumentor.go # Anthropic 插桩实现\n└── examples/ # 示例代码\n```\n\n## 环境变量\n\n除代码配置外，SDK 也支持通过环境变量进行配置：\n\n| 环境变量 | 说明 |\n|----------|------|\n| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP 导出端点 |\n\n## 关闭 SDK\n\n应用程序结束时，应优雅地关闭 SDK 以确保所有数据被正确刷新：\n\n```go\ndefer openlit.Shutdown(context.Background())\n\n---\n\n\n\n## 可观测性功能\n\n### 相关页面\n\n相关主题：[Python SDK](#python-sdk), [GPU Collector](#gpu-collector), [评估功能](#evaluations)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [src/client/src/app/(playground)/getting-started/page.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/app/(playground)/getting-started/page.tsx)\n- [sdk/python/src/openlit/instrumentation/claude_agent_sdk/__init__.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/instrumentation/claude_agent_sdk/__init__.py)\n- [sdk/python/src/openlit/instrumentation/llamaindex/utils.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/instrumentation/llamaindex/utils.py)\n- [sdk/python/src/openlit/instrumentation/langgraph/__init__.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/instrumentation/langgraph/__init__.py)\n- [sdk/python/src/openlit/instrumentation/openai/async_openai.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/instrumentation/openai/async_openai.py)\n- [sdk/typescript/src/instrumentation/llamaindex/index.ts](https://github.com/openlit/openlit/blob/main/sdk/typescript/src/instrumentation/llamaindex/index.ts)\n- [src/client/src/components/(playground)/getting-started/tracing/index.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/components/(playground)/getting-started/tracing/index.tsx)\n- [src/client/src/components/(playground)/agents/observability-block.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/components/(playground)/agents/observability-block.tsx)\n
\n\n# 可观测性功能\n\n## 概述\n\nOpenLIT 是一个基于 OpenTelemetry 原生的 GenAI 和 LLM 应用可观测性工具，旨在简化 LLM 应用与 OpenTelemetry 追踪和指标系统的集成过程。OpenLIT 通过自动插桩技术，为开发者提供开箱即用的可观测性能力，无需对现有代码进行大规模改造。资料来源：[src/client/src/app/(playground)/getting-started/page.tsx:50]()\n\n### 核心设计理念\n\nOpenLIT 的可观测性功能遵循以下设计原则：\n\n1. **OpenTelemetry 原生支持**：完全兼容 OpenTelemetry 标准协议\n2. **零侵入式集成**：通过自动插桩（Auto-Instrumentation）实现透明监控\n3. **多框架支持**：覆盖主流 LLM 框架和应用框架\n4. **语义约定合规**：遵循 GenAI 语义约定规范\n\n---\n\n## 架构设计\n\n### 系统架构图\n\n```mermaid\ngraph TD\n A[用户应用] --> B[OpenLIT SDK]\n B --> C[自动插桩层]\n C --> D[OpenTelemetry Collector]\n D --> E[追踪数据]\n D --> F[指标数据]\n D --> G[事件数据]\n \n H[Python SDK] --> C\n I[TypeScript SDK] --> C\n \n J[OpenAI] --> C\n K[Anthropic] --> C\n L[LlamaIndex] --> C\n M[LangGraph] --> C\n N[Claude Agent SDK] --> C\n \n E --> H1[追踪后端]\n F --> M1[指标后端]\n G --> E1[事件后端]\n```\n\n### 组件层次结构\n\n| 层级 | 组件 | 说明 |\n|------|------|------|\n| 应用层 | 用户代码 | 集成 OpenLIT SDK 的业务应用 |\n| SDK 层 | Python/TypeScript SDK | 提供初始化和配置接口 |\n| 插桩层 | 自动插桩模块 | 拦截并增强框架调用 |\n| 传输层 | OTLP 导出器 | 将遥测数据传输至后端 |\n| 后端层 | OpenTelemetry Collector | 收集和处理遥测数据 |\n\n---\n\n## 核心功能模块\n\n### 1. 追踪功能（Tracing）\n\nOpenLIT 的追踪功能通过包装框架的核心方法来创建分布式追踪 span，记录 LLM 调用的完整生命周期。\n\n#### 1.1 支持的框架和操作\n\n| 框架 | 操作类型 | 语义约定 |\n|------|----------|----------|\n| OpenAI | `chat`、`embedding` | `gen_ai.operation.type` |\n| Anthropic | `chat` | `gen_ai.operation.type` |\n| LlamaIndex | `query_engine_query`、`document_load`、`document_split`、`response_synthesize` | `gen_ai.operation.type` |\n| LangGraph | `execution`、`construction`、`checkpointing` | `gen_ai.operation.type` |\n| Claude Agent SDK | `invoke_agent`、`execute_tool` | `gen_ai.operation.type` |\n\n#### 1.2 LlamaIndex 操作映射\n\nOpenLIT 为 LlamaIndex 定义了精细的操作类型映射，采用简化的语义约定以提高处理效率：\n\n```python\nOPERATION_MAP = {\n # 文档加载与处理\n \"document_load\": SemanticConvention.GEN_AI_OPERATION_TYPE_RETRIEVE,\n \"document_transform\": SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,\n \"document_split\": SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,\n \n # 索引构建与管理\n \"index_construct\": SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,\n \"index_insert\": SemanticConvention.GEN_AI_OPERATION_TYPE_FRAMEWORK,\n \n # 查询引擎操作\n \"query_engine_query\": SemanticConvention.GEN_AI_OPERATION_TYPE_RETRIEVE,\n \"query_engine_query_async\": SemanticConvention.GEN_AI_OPERATION_TYPE_RETRIEVE,\n \n # 检索器操作\n \"retriever_retrieve\": SemanticConvention.GEN_AI_OPERATION_TYPE_RETRIEVE,\n}\n```\n\n资料来源：[sdk/python/src/openlit/instrumentation/llamaindex/utils.py:14-36]()\n\n#### 1.3 TypeScript SDK 的 LlamaIndex 插桩\n\nTypeScript SDK 采用原型方法打补丁的方式实现 LlamaIndex 插桩：\n\n```typescript\n// 文档操作（框架 / 检索 span）\nthis._patchProto(m, ['SimpleDirectoryReader'], 'loadData',\n LlamaIndexWrapper._patchFrameworkMethod(tracer, 'document_load'));\n\n// 文本分割\nthis._patchProto(m, ['SentenceSplitter', 'NodeParser'], 'getNodesFromDocuments',\n LlamaIndexWrapper._patchFrameworkMethod(tracer, 'document_split'));\n\n// 检索操作\nthis._patchProto(m, ['BaseRetriever'], 'retrieve',\n LlamaIndexWrapper._patchFrameworkMethod(tracer, 'retriever_retrieve'));\n```\n\n资料来源：[sdk/typescript/src/instrumentation/llamaindex/index.ts:78-92]()\n\n### 2. 指标功能（Metrics）\n\nOpenLIT 自动收集并记录关键性能指标，包括：\n\n| 指标类型 | 说明 | 记录方式 |\n|----------|------|----------|\n| 请求计数 | LLM 调用总次数 | 计数器 |\n| 令牌使用 | 输入/输出令牌数 | 计量器 |\n| 响应延迟 | 请求到响应的耗时 | 直方图 |\n| 错误率 | 失败请求的比例 | 计数器 |\n\n#### 指标收集流程\n\n```mermaid\ngraph LR\n A[LLM 调用] --> B[插桩包装器]\n B --> C{是否禁用指标?}\n C -->|否| D[记录完成指标]\n C -->|是| E[跳过指标记录]\n D --> F[record_completion_metrics]\n F --> G[更新指标后端]\n \n style C fill:#f9f,stroke:#333\n style D fill:#bbf,stroke:#333\n```\n\n### 3. 事件功能（Events）\n\nOpenLIT 通过事件提供者（Event Provider）记录重要的应用事件，支持日志级别的事件追踪：\n\n```python\nevent_provider = _logs.get_logger_provider().get_logger(__name__)\n```\n\n事件功能允许开发者在追踪 span 之外记录额外的上下文信息，增强问题的排查能力。\n\n### 4. 异常处理\n\nOpenLIT 的插桩层实现了完善的异常处理机制，确保即使在监控过程中发生错误也不会影响应用正常运行：\n\n```python\nexcept Exception as e:\n handle_exception(span, e)\n if not disable_metrics and metrics:\n record_completion_metrics(\n metrics,\n # ... 参数配置\n error_type=type(e).__name__ or \"_OTHER\",\n )\n```\n\n资料来源：[sdk/python/src/openlit/instrumentation/openai/async_openai.py:95-108]()\n\n---\n\n## SDK 使用指南\n\n### Python SDK\n\n#### 安装\n\n```bash\npip install openlit\n```\n\n#### 初始化配置\n\n```python\nimport openlit\n\nopenlit.init(otlp_endpoint=\"http://127.0.0.1:4318\")\n```\n\n或者通过环境变量配置：\n\n```bash\nexport OTEL_EXPORTER_OTLP_ENDPOINT=\"http://127.0.0.1:4318\"\n```\n\n#### 完整使用示例\n\n```python\nfrom openai import OpenAI\nimport openlit\n\nopenlit.init(otlp_endpoint=\"http://127.0.0.1:4318\")\n\nclient = OpenAI(api_key=\"YOUR_OPENAI_KEY\")\n\nchat_completion = client.chat.completions.create(\n messages=[\n {\n \"role\": \"user\",\n \"content\": \"What is LLM Observability?\",\n }\n ],\n model=\"gpt-3.5-turbo\",\n)\n```\n\n资料来源：[src/client/src/app/(playground)/getting-started/page.tsx:90-110]()\n\n### TypeScript SDK\n\n#### 安装\n\n通过 npm 或 yarn 安装 TypeScript SDK\n\n#### 初始化配置\n\n```typescript\nimport openlit from 'openlit';\n\nopenlit.init({\n otlpEndpoint: \"http://127.0.0.1:4318\"\n});\n```\n\n#### 完整使用示例\n\n```typescript\nimport OpenAI from 'openai';\nimport openlit from 'openlit';\n\nopenlit.init({ otlpEndpoint: \"http://127.0.0.1:4318\" });\n\nconst client = new OpenAI({\n apiKey: process.env.OPENAI_API_KEY\n});\n\nconst chatCompletion = await client.chat.completions.create({\n messages: [{ role: 'user', content: 'What is LLM Observability?' }],\n model: 'gpt-3.5-turbo',\n});\n```\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:95-110]()\n\n---\n\n## 插桩模块架构\n\n### 基类设计\n\nOpenLIT 的所有插桩模块都继承自 `BaseInstrumentor` 基类，提供统一的接口规范：\n\n```python\nclass ClaudeAgentSDKInstrumentor(BaseInstrumentor):\n \"\"\"OTel GenAI semantic convention compliant instrumentor for Claude Agent SDK.\"\"\"\n \n def instrumentation_dependencies(self) -> Collection[str]:\n return _instruments # 声明依赖版本\n \n def _instrument(self, **kwargs):\n # 执行插桩逻辑\n tracer = trace.get_tracer(__name__)\n # ... 配置和包装逻辑\n```\n\n资料来源：[sdk/python/src/openlit/instrumentation/claude_agent_sdk/__init__.py:26-38]()\n\n### LangGraph 插桩分类\n\nLangGraph 的插桩功能分为三大类：\n\n| 操作类别 | 说明 | 包含操作 |\n|----------|------|----------|\n| 执行操作 | 图执行相关 | `invoke`、`ainvoke`、`stream` 等 |\n| 构建操作 | 组件构建 | `add_node`、`add_edge` 等 |\n| 检查点操作 | 状态保存 | `get`、`put` 等 |\n\n```python\n# 执行操作包装\nself._wrap_execution_operations(\n EXECUTION_OPERATIONS,\n version,\n environment,\n application_name,\n tracer,\n pricing_info,\n capture_message_content,\n metrics,\n disable_metrics,\n)\n\n# 检查点操作包装\nself._wrap_checkpoint_operations(\n version,\n environment,\n application_name,\n tracer,\n pricing_info,\n capture_message_content,\n metrics,\n disable_metrics,\n)\n```\n\n资料来源：[sdk/python/src/openlit/instrumentation/langgraph/__init__.py:50-100]()\n\n---\n\n## 配置选项\n\n### 初始化参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `otlp_endpoint` | string | - | OTLP 导出器端点 |\n| `environment` | string | \"default\" | 运行环境标识 |\n| `application_name` | string | \"default\" | 应用名称 |\n| `pricing_info` | dict | {} | 定价信息映射 |\n| `capture_message_content` | bool | False | 是否捕获消息内容 |\n| `metrics` | bool | True | 是否启用指标收集 |\n| `disable_metrics` | bool | False | 是否禁用指标 |\n\n### 环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP 端点地址 |\n| `OTEL_SERVICE_NAME` | 服务名称 |\n\n---\n\n## 前端可视化\n\n### 可观测性状态显示\n\nOpenLIT 前端提供了实时的可观测性状态展示功能：\n\n```typescript\n// SDK 启用状态标识\n{isStatic ? (\n \n \n {getMessage().AGENTS_SDK_ENABLED_VIA}\n \n) : pending ? (\n // 待处理状态\n)}\n```\n\n资料来源：[src/client/src/components/(playground)/agents/observability-block.tsx:45-55]()\n\n### 版本追踪\n\n前端组件支持追踪不同版本的代理（Agent）使用情况：\n\n| 显示字段 | 说明 |\n|----------|------|\n| 首次出现时间 | `first_seen` |\n| 最后出现时间 | `last_seen` |\n| 请求计数 | `request_count` |\n| 主要模型 | `primary_model` |\n\n资料来源：[src/client/src/components/(playground)/agents/version-drawer.tsx:80-95]()\n\n---\n\n## 默认凭证\n\n首次部署 OpenLIT 后，访问前端界面需要使用以下默认登录凭证：\n\n| 字段 | 值 |\n|------|-----|\n| Email | user@openlit.io |\n| Password | openlituser |\n\n资料来源：[src/client/src/app/(playground)/getting-started/page.tsx:60-65]()\n\n---\n\n## 技术栈总结\n\n### 核心技术依赖\n\n| 组件 | 用途 |\n|------|------|\n| OpenTelemetry | 遥测数据标准 |\n| wrapt | 函数包装 |\n| opentelemetry-instrumentation | 自动插桩框架 |\n\n### 支持的框架版本\n\n| 框架 | 最低版本要求 |\n|------|--------------|\n| Claude Agent SDK | >= 0.1.0 |\n| OpenAI | - |\n| LlamaIndex | - |\n| LangGraph | - |\n\n---\n\n## 总结\n\nOpenLIT 的可观测性功能通过标准化的 OpenTelemetry 集成，为 LLM 应用提供了全面的监控能力。其核心优势包括：\n\n- **多框架支持**：统一覆盖主流 GenAI 和 LLM 框架\n- **零侵入集成**：通过自动插桩实现快速部署\n- **标准化输出**：遵循 OpenTelemetry 和 GenAI 语义约定\n- **灵活配置**：支持多种初始化方式和配置参数\n- **优雅降级**：异常情况下不影响应用运行\n\n---\n\n\n\n## 评估功能\n\n### 相关页面\n\n相关主题：[Guardrails与规则引擎](#guardrails), [可观测性功能](#observability)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [sdk/python/src/openlit/guard/__init__.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/guard/__init__.py)\n- [src/client/src/utils/breadcrumbs.ts](https://github.com/openlit/openlit/blob/main/src/client/src/utils/breadcrumbs.ts)\n- [src/client/src/components/(playground)/getting-started/tracing/index.tsx](https://github.com/openlit/openlit/blob/main/src/client/src/components/(playground)/getting-started/tracing/index.tsx)\n- [src/client/README.md](https://github.com/openlit/openlit/blob/main/src/client/README.md)\n- [sdk/python/src/openlit/instrumentation/claude_agent_sdk/__init__.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/instrumentation/claude_agent_sdk/__init__.py)\n\n
\n\n# 评估功能\n\n## 概述\n\nOpenLIT 的评估功能（Evaluation）是平台核心能力之一，旨在为 LLM 应用提供可量化的质量评估机制。通过集成 OpenTelemetry 原生架构，OpenLIT 能够对 AI 应用的响应质量、成本效率和性能表现进行全面的监控与评估。\n\n> **注意**：当前从源码中获取的评估功能相关文档较为有限，以下内容基于可观察到的系统架构和组件进行阐述。\n\n## 评估设置页面\n\n### 路由配置\n\n评估功能在客户端应用中具有独立的路由入口。根据路由配置，评估相关页面包括：\n\n| 路由路径 | 页面标题 | 面包屑导航 |\n|---------|---------|-----------|\n| `/evaluations/settings` | 评估设置（Evaluation Settings） | Settings → Evaluation Settings |\n\n资料来源：[src/client/src/utils/breadcrumbs.ts:1-150]()\n\n### 评估设置界面\n\n评估设置页面允许用户配置评估相关的参数和行为。页面采用标准的设置界面布局，与平台其他设置页面保持一致的交互模式。\n\n## 评估执行机制\n\n### SDK 层面的评估支持\n\nOpenLIT Python SDK 提供了多层次的支持机制，虽然直接的评估执行文件在当前源码上下文中未完全展示，但从系统架构可以看出评估功能与其他 SDK 组件的集成关系。\n\n```mermaid\ngraph TB\n subgraph \"Python SDK\"\n A[openlit.init] --> B[Guard System]\n B --> C[PII Detection]\n B --> D[Prompt Injection Detection]\n B --> E[Moderation]\n B --> F[Topic Restriction]\n end\n \n subgraph \"Evaluation Layer\"\n G[Evaluation Settings] --> H[Run Evaluation]\n H --> I[Results Analysis]\n end\n \n C --> G\n D --> G\n E --> G\n F --> G\n```\n\n## Guard 系统与评估质量保障\n\n### Guard 组件架构\n\nOpenLIT 的 Guard 系统是评估功能的重要组成部分，提供生产级的安全保障机制。Guard 组件可以作为评估流程中的质量过滤器使用。\n\n资料来源：[sdk/python/src/openlit/guard/__init__.py:1-47]()\n\n### 核心 Guard 类\n\n| 类名 | 功能描述 | 使用场景 |\n|-----|---------|---------|\n| `PII` | 个人身份信息检测与处理 | 隐私合规评估 |\n| `PromptInjection` | 提示词注入攻击检测 | 安全性评估 |\n| `SensitiveTopic` | 敏感话题识别 | 内容安全评估 |\n| `TopicRestriction` | 话题范围限制 | 主题一致性评估 |\n| `Moderation` | 内容审核 | 合规性评估 |\n| `Schema` | 输出结构验证 | 格式正确性评估 |\n| `Custom` | 自定义 Guard 逻辑 | 定制化评估规则 |\n\n### Guard 基础类型\n\n```python\n# 基础类型定义\nGuard # Guard 基类\nGuardAction # Guard 执行动作\nGuardPhase # Guard 执行阶段\nGuardResult # Guard 执行结果\nPipelineResult # 管道执行结果\n```\n\n资料来源：[sdk/python/src/openlit/guard/__init__.py:11-24]()\n\n### Guard 错误类型\n\n| 错误类 | 说明 |\n|-------|------|\n| `GuardError` | 基础 Guard 错误 |\n| `GuardDeniedError` | Guard 拒绝执行错误 |\n| `GuardTimeoutError` | Guard 执行超时错误 |\n| `GuardConfigError` | Guard 配置错误 |\n\n资料来源：[sdk/python/src/openlit/guard/__init__.py:26-31]()\n\n## 评估集成方式\n\n### 初始化配置\n\n在应用代码中集成评估功能的标准方式：\n\n```python\nimport openlit\n\n# 初始化 OpenLIT\nopenlit.init(\n otlp_endpoint=\"http://127.0.0.1:4318\",\n # 评估相关配置\n)\n```\n\n资料来源：[src/client/src/components/(playground)/getting-started/tracing/index.tsx:1-100]()\n\n### Guard 与评估结合使用\n\n```python\nimport openlit\n\n# 初始化并启用 Guard\nopenlit.init(\n guards=[\n openlit.PII(action=\"redact\"),\n openlit.Moderation(threshold=0.8)\n ]\n)\n```\n\n## 技术架构\n\n### OpenTelemetry 原生集成\n\nOpenLIT 采用 OpenTelemetry 标准进行数据采集和传输，确保评估数据与追踪、指标数据的一致性。\n\n```mermaid\ngraph LR\n A[Application] -->|Traces/Metrics| B[OpenLIT SDK]\n B -->|OTLP| C[OpenTelemetry Collector]\n C -->|Data| D[OpenLIT Backend]\n D -->|Display| E[UI Dashboard]\n \n F[Evaluation Engine] -->|Quality Scores| D\n G[Guard System] -->|Security Results| F\n```\n\n### 追踪与评估关联\n\n评估结果与应用的追踪数据关联存储，用户可以在 OpenLIT 前端界面中同时查看：\n\n- 追踪详情（Traces）\n- 评估分数（Evaluation Scores）\n- Guard 事件（Guard Events）\n- 成本与延迟指标（Cost & Latency Metrics）\n\n## 前端组件结构\n\n### 评估相关路由\n\n客户端应用使用 Next.js 的文件路由系统，评估功能页面位于：\n\n```\nsrc/client/src/app/(playground)/evaluations/\n```\n\n### 导航与面包屑\n\n评估功能通过统一的导航系统与平台其他功能整合，用户可以从主导航直接访问评估设置。\n\n资料来源：[src/client/src/utils/breadcrumbs.ts:60-75]()\n\n## SDK 仪器化支持\n\n### Claude Agent SDK 仪器化\n\nOpenLIT 支持对 Claude Agent SDK 进行仪器化，自动采集代理执行过程中的评估相关数据：\n\n资料来源：[sdk/python/src/openlit/instrumentation/claude_agent_sdk/__init__.py:1-50]()\n\n支持的仪器化操作：\n\n| 操作类型 | 追踪事件 | 说明 |\n|---------|---------|------|\n| `invoke_agent` | Agent 调用 | 追踪代理执行 |\n| `execute_tool` | 工具执行 | 追踪工具使用 |\n| `query` | 查询操作 | 追踪查询请求 |\n\n## 使用限制与注意事项\n\n### 当前源码限制\n\n从当前获取的源码上下文来看，评估功能的具体实现细节（如评估算法、评分标准等）需要在以下方面获取更多源码：\n\n1. 评估执行核心逻辑文件\n2. 评估结果存储与查询 API\n3. 前端评估配置界面组件\n4. 评估报告生成模块\n\n### 建议\n\n- 访问 OpenLIT 官方文档获取完整的评估功能使用指南\n- 查看 `sdk/python/src/openlit/evaluation/` 目录下的具体实现\n- 参考前端 `src/client/src/lib/platform/evaluation/` 目录了解评估流程\n\n## 相关资源\n\n| 资源 | 链接 |\n|------|------|\n| OpenLIT 官方文档 | https://docs.openlit.io |\n| GitHub 仓库 | https://github.com/openlit/openlit |\n| Python SDK | https://github.com/openlit/openlit/tree/main/sdk/python |\n| TypeScript SDK | https://github.com/openlit/openlit/tree/main/sdk/typescript |\n\n---\n\n*本文档基于 OpenLIT 开源项目源码生成，如有疏漏或更新延迟，请以官方最新文档为准。*\n\n---\n\n\n\n## Guardrails与规则引擎\n\n### 相关页面\n\n相关主题：[评估功能](#evaluations), [可观测性功能](#observability)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [sdk/python/src/openlit/guard/__init__.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/guard/__init__.py)\n- [sdk/python/src/openlit/guard/pii.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/guard/pii.py)\n- [sdk/python/src/openlit/guard/_base.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/guard/_base.py)\n- [sdk/python/src/openlit/guard/_pipeline.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/guard/_pipeline.py)\n- [sdk/python/src/openlit/guard/prompt_injection.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/guard/prompt_injection.py)\n- [sdk/python/src/openlit/guard/sensitive_topic.py](https://github.com/openlit/openlit/blob/main/sdk/python/src/openlit/guard/sensitive_topic.py)\n
\n\n# Guardrails与规则引擎\n\n## 概述\n\nOpenLIT Guardrails是面向LLM应用的生产级安全防护系统，提供开箱即用的防护栏（Guardrails）和灵活可扩展的规则引擎（Rule Engine）。该系统通过在LLM应用的关键阶段注入检测逻辑，自动识别并处理敏感信息泄露、提示词注入攻击、违禁内容等安全风险。\n\nGuardrails系统基于OpenTelemetry语义约定设计，支持preflight（前置检查）和postflight（后置检查）两个执行阶段，可无缝集成到现有LLM应用架构中。资料来源：[sdk/python/src/openlit/guard/__init__.py:1-12]()\n\n## 架构设计\n\n### 核心组件\n\nOpenLIT Guardrails系统由以下核心组件构成：\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| Guard基类 | `guard/_base.py` | 定义所有Guard的通用接口和生命周期 |\n| Pipeline管道 | `guard/_pipeline.py` | 编排多个Guard的执行顺序和结果聚合 |\n| PII检测器 | `guard/pii.py` | 识别API密钥、个人身份信息等敏感数据 |\n| 提示词注入检测器 | `guard/prompt_injection.py` | 识别恶意提示词注入攻击 |\n| 敏感话题检测器 | `guard/sensitive_topic.py` | 检测涉及敏感话题的内容 |\n| 主题限制器 | `guard/topic_restriction.py` | 限制对话内容的主题范围 |\n| 内容审核器 | `guard/moderation.py` | 审核生成内容是否合规 |\n| Schema验证器 | `guard/schema.py` | 验证输出是否符合预定义Schema |\n| 自定义Guard | `guard/custom.py` | 支持用户自定义检测规则 |\n\n资料来源：[sdk/python/src/openlit/guard/__init__.py:14-36]()\n\n### 架构流程图\n\n```mermaid\ngraph TD\n A[LLM请求入口] --> B[Preflight阶段]\n B --> C{Guard Pipeline}\n C --> D1[PII检测]\n C --> D2[提示词注入检测]\n C --> D3[敏感话题检测]\n C --> D4[自定义Guard]\n D1 --> E{检测结果}\n D2 --> E\n D3 --> E\n D4 --> E\n E -->|通过| F[调用LLM]\n E -->|拒绝| G[返回GuardDeniedError]\n E -->|警告| H[记录日志继续执行]\n F --> I[Postflight阶段]\n I --> J1[输出PII检测]\n I --> J2[内容审核]\n I --> J3[Schema验证]\n J1 --> K[返回结果]\n J2 --> K\n J3 --> K\n```\n\n## Guard基类设计\n\n### 执行阶段\n\nGuard系统定义了两个核心执行阶段：\n\n| 阶段 | 说明 | 适用场景 |\n|------|------|----------|\n| `PREFLIGHT` | 在LLM调用前执行 | 输入内容检测、提示词保护 |\n| `POSTFLIGHT` | 在LLM调用后执行 | 输出内容审核、数据脱敏 |\n\n资料来源：[sdk/python/src/openlit/guard/_base.py]()\n\n### 动作类型\n\n每个Guard支持三种响应动作：\n\n| 动作 | 行为 | 返回结果 |\n|------|------|----------|\n| `redact` | 自动脱敏/替换敏感内容 | 返回脱敏后的文本 |\n| `deny` | 直接拒绝请求 | 抛出`GuardDeniedError` |\n| `warn` | 仅记录事件不阻断 | 返回原始文本并附带警告信息 |\n\n资料来源：[sdk/python/src/openlit/guard/_base.py]()\n\n### 错误类型\n\n| 错误类 | 触发条件 |\n|--------|----------|\n| `GuardError` | 通用Guard异常 |\n| `GuardDeniedError` | 内容被拒绝时抛出 |\n| `GuardTimeoutError` | 检测超时 |\n| `GuardConfigError` | 配置错误 |\n\n## PII检测器详解\n\n### 功能概述\n\nPII检测器是OpenLIT Guardrails最核心的组件之一，使用约25种高置信度正则表达式模式，在小于1毫秒的时间内完成本地检测。该检测器支持识别API密钥、PII个人信息和各类敏感凭证。\n\n### 支持的检测类型\n\n| 类别 | 检测项目 | 正则模式示例 |\n|------|----------|--------------|\n| API密钥 | OpenAI API Key | `sk-(?:proj-)?[A-Za-z0-9_-]{20,}` |\n| API密钥 | Anthropic API Key | `sk-ant-[A-Za-z0-9_-]{20,}` |\n| API密钥 | AWS Access Key | `AKIA[0-9A-Z]{16}` |\n| API密钥 | GCP API Key | `AIza[0-9A-Za-z_-]{35}` |\n| 令牌 | GitHub Token | `(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{36,}` |\n| 证书 | 客户端证书 | PEM格式证书检测 |\n| 凭证 | 私钥检测 | RSA/DSA/EC私钥模式 |\n| 凭证 | Azure凭据 | Azure服务主体格式 |\n\n资料来源：[sdk/python/src/openlit/guard/pii.py:1-45]()\n\n### 使用方式\n\n```python\nimport openlit\n\n# 基础使用 - 自动脱敏\nopenlit.init(guards=[openlit.PII(action=\"redact\")])\n\n# 自定义检测模式\nopenlit.init(guards=[\n openlit.PII(\n action=\"deny\",\n custom_patterns={\n \"custom-secret\": r\"secret-[A-Za-z0-9]{16}\",\n \"internal-id\": r\"INT-\\d{8}\"\n }\n )\n])\n```\n\n### 脱敏机制\n\n当检测到敏感信息时，PII检测器会将匹配内容替换为标准化的占位符格式：\n\n```\n[REDACTED: