Opik 外部集成开发指南在仓库之外构建 opik-* 插件与第三方生态集成【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm导读Opik 的生态集成并非全部由 SDK 仓库内部提供相当一部分集成以独立opik-*包如opik-openclaw、opik-claude-code-plugin或第三方宿主项目上游贡献如 LiteLLM、Dify 中的 Opik 支持的形式存在。本文基于仓库内.agents/skills/opik-external-integrations/技能体系系统讲解在当前仓库之外构建 Opik 集成的完整方法论——包括两种集成形态的区分、激活门槛、两条核心原则、前置问卷、参考资料索引以及从调研宿主仓库到最终提 PR 的八个阶段工作流。读完本文你将掌握如何在保持宿主仓库惯例的前提下、只通过 Opik 已发布的公开 API 构建可验证的外部集成并能用 Opik MCP 闭环验证日志落库的正确性。什么是外部集成两种集成形态外部集成external integration指代码不在当前仓库内的 Opik 集成。它区别于 SDK 内建集成位于sdks/python/src/opik/integrations/或sdks/typescript/src/opik/integrations/具体有两种形态形态定义示例独立opik-*包 / 插件拥有自己的仓库或包依赖已发布的Opik SDKopik-openclawOpenClaw 插件、opik-claude-code-pluginClaude Code 插件上游贡献在已拥有自身日志/回调/插件体系的第三方项目中加入 Opik 支持LiteLLM 中的 Opik 回调、Dify 中的 Opik 集成两种形态的区分决定了后续所有工作的走向独立包要自己设计包结构与发布方式而上游贡献则必须完全服从宿主项目的既有约定。激活门槛先回答代码放在哪里这是整个技能体系的第一道门文档中以醒目的 Activation gate 标注目标位于外部仓库或外部包→ 使用opik-external-integrations技能本文主题目标要放在sdks/python/src/opik/integrations/或sdks/typescript/src/opik/integrations/内部 → 走内部技能opik-integrations其入口见 .agents/skills/opik-integrations/SKILL.md无法判断时先问代码放哪里这个问题再路由到对应技能。这一门槛的背后是现实约束当前仓库内部的模块opik.decorator.*、rest_api、消息处理内部实现等在仓库之外既不可用也不是稳定的对外契约。外部集成只能面向发布后的 SDK 表面。两条让外部工作与众不同的核心原则原则一遵循宿主仓库的惯例而不是本仓库的惯例外部集成的工作环境由目标项目决定包括目录结构、依赖管理、lint/format、测试框架、文档规范与贡献指南。不能把本仓库的sdks/布局、fake_backend测试设施或 Fern 文档体系强加到外部仓库上。正确做法是阅读宿主项目的CONTRIBUTING/AGENTS.md镜像其最接近的既有集成或插件clone the sibling按宿主的方式组织代码、写测试、写文档。原则二只消费 Opik 的已发布公开 API外部集成能使用的唯一 Opik 表面是用户日常面对的那一层Pythonimport opikopik.track与track_*装饰器opik.Opik()客户端opik.opik_context写入 span 数据client.flush()TypeScriptopik包中的Opik客户端、track与领域对象、flushAll()REST API当宿主运行时没有合适的 SDK 时直接调用 Opik 的 REST 接口。上述公开 API 面在当前仓库中均有真实实现可供对照Python 侧的统一出口见 sdks/python/src/opik/init.py导出了track、flush_tracker、Opik、get_global_client、opik_context、is_tracing_active、set_tracing_active等LLMProvider枚举在 sdks/python/src/opik/types.py 中定义REST 层则对应后端 apps/opik-backend/src/main/java 暴露的 HTTP 接口。外部集成绝不能import opik.decorator.*之类的内部模块——它们不属于稳定契约一旦仓库内部重构就会失效。前置问卷Phase 0动手之前先问清六件事开始任何工作之前用自然语言收集以下信息自由形式提问不要替用户指定目标外部目标——仓库 URL / 包名附带参考链接文档、宿主项目贡献指南若是独立包明确预期的 Opik 制品名如opik-openclaw集成形态——独立opik-*包/插件、第三方项目LiteLLM、Dify 等上游贡献、还是工具/IDE 插件宿主语言/技术栈——Python、TypeScript/Node 或其他包管理器与运行时Opik 代码的落点——宿主仓库内的具体路径哪个插件/集成目录或新独立包的布局宿主惯例——其CONTRIBUTING/AGENTS.md链接、测试框架、文档位置验证与凭据——如何在本地运行宿主以实际触发集成以及所需的 API 密钥provider 与 Opik是否可用。收集完毕后在获取代码前先查references.md见下节从已知集成中挑选最接近的作为克隆源全新独立包则从 cookiecutter 模板起步。然后获取仓库clone/checkout 到 scratchpad并在改动任何内容之前确认它可以正常构建/安装。参考资料索引站在已有集成的肩膀上references.md 维护了一份已知外部集成清单用于给调研阶段做种子数据。当目标命中或近似清单中的条目时直接以其仓库和文档为起点而不是从零调研。独立opik-*包comet-ml 组织opik-project-templatecookiecutter 脚手架全新独立包的标准起点、opik-openclawOpenClaw 插件导出 traces、成本、tokens、错误、opik-claude-code-plugin、opik-codex-plugin、opik-kong-pluginKong AI 网关插件上游贡献宿主仓库 Opik 文档页LiteLLMOpik logger 位于其litellm/integrations/opik/、Dify、n8n、Flowise、Langflow。这些宿主集成对应的 Opik 文档页源文件就在本仓库内路径为 apps/opik-documentation/documentation/fern/docs-v2/integrations/可找到litellm.mdx、dify.mdx、n8n.mdx、flowise.mdx、langflow.mdx、openclaw.mdx、openai-codex.mdx、kong-ai-gateway.mdx等页面。仓库还提示文档集成索引overview.mdx是已发布集成的权威清单其中大量条目属于外部/宿主侧实现。注意references.md 自己强调仓库会变动其中的路径只作为起点提示而非保证使用前需对照活跃仓库确认。端到端工作流八个阶段详解完整 playbook 见 workflow.md默认自主运行自主完成所有准备、跑完所有阶段、自验证并汇报仅在遇到真正的阻塞无仓库访问权、缺失凭据且无回退方案、后端不可达、产品决策含糊时提前停下并汇报已完成部分用户也可要求交互模式——在 Phase 3 写代码前暂停等待设计审批。无论哪种模式都必须以 Phase 8 报告收尾且每个支持声明必须有通过的测试或经 MCP 验证的 trace 作为证据。Phase 0 —— 问卷 获取代码按上文问卷收集六要素查 references.md 选定克隆源然后 clone/checkout 宿主仓库到 scratchpad确认其能构建/安装后用一句话复述答案并继续。Phase 1 —— 调研宿主仓库回答四个问题为接入点选型提供依据扩展点宿主为可观测性提供的接入位置——回调/钩子接口、插件/入口点注册表、中间件还是环境变量驱动的 logger。Opik 就挂在这里最接近的既有集成宿主内如何集成其他可观测性/日志厂商克隆其结构、注册方式与风格依赖规则宿主如何声明可选/extra 依赖、测试框架、lint/format 与文档规范钩子处可用的宿主数据输入、输出、模型、用量、错误、时延及其形状。Phase 2 —— 调研 Opik 的公开表面从三条路中挑选绝不用本仓库内部模块Pythonimport opik、opik.track、track_*装饰器或opik.Opik()客户端opik.opik_context写 span 数据client.flush()落库TypeScriptopik包——Opik客户端、track、领域对象flushAll()REST宿主运行时无适配 SDK 时使用。同时确认要依赖的已发布 SDK 版本以及宿主将如何配置 Opik环境变量OPIK_API_KEY、base URL、workspace、project——对应OPIK_URL_OVERRIDE/OPIK_WORKSPACE/OPIK_PROJECT_NAME这类配置入口。Phase 3 —— 设计关卡落笔写清楚使用的宿主扩展点Opik 客户端如何创建、配置与 flush宿主数据 → Opik trace/span 字段的映射input/output/model/provider/usage/error/span-type宿主仓库内的文件布局镜像其同级集成宿主用户启用该集成所需的公开注册方式。自主模式下把设计写进报告交互模式下呈现并等待批准。Phase 4 —— 实现镜像宿主最接近的同级集成及其风格依赖已发布的 Opik SDK保持集成的透明性——包装、捕获、重抛当 Opik 未配置时不得改变宿主行为按宿主生命周期请求结束、进程退出、显式钩子适时 flush。Phase 5 —— 通过 Opik MCP 验证这是集成真的记录正确的证据不能只靠读代码。循环如下配置 Opik 环境变量让日志写入已连接 Opik MCP 所读取的 workspace——注意连接 MCP 的后端往往与本地~/.opik.config指向不同例如 MCP 指向托管环境而本地指向localhost需先确认二者一致或改用 SDK 读回方式验证启用集成运行宿主走主流程非流式、流式及其他附加路径随后 flush通过 MCP 读回 trace/spans先list再read对照 Phase 3 的映射核对 trace 树每个顶层调用一条 tracespan 层级与type正确模型调用为llminput/output 形态良好usage 含 token 计数model/provider 已设置错误被记录并仍然重抛循环直至一致。当 MCP 无法读取可写的后端时可用SDK 读回作为等价证据client opik.Opik()后client.search_traces(project_name...)再client.search_spans(trace_id...)按同一清单断言并在报告中注明读回途径。Phase 6 —— 测试使用宿主自己的测试框架与惯例而不是本仓库的fake_backend/testlib那是仓库内部设施。镜像宿主测试其他集成的方式——在宿主边界处 mock Opik 客户端/HTTP或对捕获的调用做断言。覆盖范围与 Phase 5 验证的流程保持一致。Phase 7 —— 文档遵循宿主文档规范其 README / 文档站 / examples 目录。可选地在 Opik 侧补充一个指向该外部集成的文档页借助write-docs技能且只使用凭据占位符如API_KEY绝不写真实密钥。Phase 8 —— 报告产出一份高层报告包含集成概况——外部目标、形态、宿主扩展点、使用的 Opik 公开 API、依赖的已发布 SDK 版本做了什么——获取的仓库、新增/修改的文件给出宿主内路径、宿主用户如何启用验证证据——MCP trace id 与 project、宿主测试结果支持的流程与测试覆盖——一张表每个用户可见流程 × 是否实现 × 宿主测试按名× 是否 MCP 验证明确标注已实现但未测试与未实现的流程不支持项 / 限制——范围外的钩子、宿主版本约束、环境/后端阻塞后续与 PR——按宿主贡献指南如何开上游 PR分支/提交、维护者评审要点。与内部集成技能的分工机制知识共享落点不同外部集成与内部 SDK 集成opik-integrations在机制层面是同一套知识——provider/框架如何暴露钩子、流式、用量等这正是 python.md 与 typescript.md 讲解的内容方法打补丁、回调处理器、OTel。但外部集成应用这些模式时有两个硬约束针对已发布的 SDK 表面并且放在宿主仓库的结构内。内部技能中的模式选型表可作参考目标形态Python 模式TypeScript 模式可克隆的同级带方法的 SDK 客户端多数 provider方法打补丁BaseTrackDecorator子类Proxy 包装openai/带回调/tracer 接口的框架纯回调BaseTracer回调处理器langchain/已发出 OpenTelemetry span 的框架OTelOTel exporterotel/依赖的技能与分工不要重复造轮子外部集成工作栈在三个既有技能之上opik/instrument——面向用户的公开 API 表面也是外部消费 Opik 的正确方式opik-integrations——集成机制模式打补丁/回调/OTel与字段映射write-docs——仅当同时要新增 Opik 侧文档页时使用。完成定义Definition of Done一项外部集成工作只有在同时满足以下条件才算完成宿主 checkout 内实现达到可合并质量MCP 验证通过或缺失原因被明确报告按宿主惯例新增测试且全部通过宿主文档已更新报告已产出。此外如果在本仓库的.agents/下改动过文件需运行make claude重新生成技能相关产物。小结Opik 外部集成是一条与 SDK 内建集成并列但约束不同的开发路径形态上分为独立opik-*包与第三方上游贡献执行上以宿主惯例优先 只消费已发布公开 API为两条铁律流程上由前置问卷、参考资料索引与八个阶段工作流构成闭环并以 Opik MCP 验证作为支持声明的硬证据。这套方法论的价值在于让任何仓库外的集成都站在 Opik 稳定的公开接口之上同时完全融入宿主生态的代码、测试与文档习惯——这也正是opik-openclaw、LiteLLM、Dify 等既有外部集成得以长期维护的模式基础。【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考