Opik Python SDK REST API 指南通过rest_client直接调用平台底层接口【免费下载链接】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 Python SDK 的 REST API 客户端能力如何通过opik.Opik()实例上的rest_client属性直接调用 Opik 平台的全部底层 HTTP 接口完成高级过滤查询、批量操作、自定义集成等高层 SDK 未覆盖的操作。读完本文你将掌握rest_client的获取方式、Traces/Datasets/Experiments 三大高频场景的调用模式、分页响应结构与异常处理策略并能结合源码理解其与高层 SDK 的关系及兼容性边界。什么是rest_clientOpik 的高层 Python SDK 封装了大多数日常操作打点追踪、数据集管理、实验评估等但它并不是平台能力的全集。为此SDK 在客户端对象上暴露了一个rest_client属性直接指向底层 REST API 客户端让进阶用户可以在需要时绕过高层封装直接发起 API 调用从而获得 Opik 平台全部功能的访问权限。在源码中该属性的定义位于 opik_client.py其返回类型为rest_api_client.OpikApi即 Fern 根据 Opik 的 API 定义自动生成的客户端类定义于 rest_api/client.py。[!WARNING]兼容性警告REST 客户端不保证与未来 SDK 版本向后兼容。它提供了一种便捷方式使用 Opik 当前的 REST API但由于 Opik 的 REST API 契约可能发生变化不建议重度依赖其接口。如果你的代码直接调用rest_client在升级 SDK 后需要重新验证相关调用。何时使用 REST API根据官方文档overview.rst当你遇到以下场景时REST API 客户端尤其有用执行高层 SDK 未提供的操作例如批量删除、按环境管理、直接读取原始返回值等构建自定义集成或工具将 Opik 能力嵌入自己的脚本、CLI 或平台使用高级过滤与查询能力REST API 暴露了完整的过滤算子可组合出复杂查询条件实现批量操作以提升性能例如批量写入数据集条目、批量删除 Traces处理特定用例所需的原始 API 响应高层 SDK 通常会做类型转换与封装REST 客户端可以拿到更贴近接口的原始结构。此外从源码看Opik 高层 SDK 自身的许多功能也正是通过rest_client实现的——例如 opik_client.py 中批量删除 Traces 使用self._rest_client.traces.delete_traces(idsbatch)环境管理使用self._rest_client.environments.*系列方法数据集查询也经由self._rest_client.datasets.get_dataset_by_identifier(...)见 opik_client.py。这意味着你直接使用rest_client时实际上是在与高层 SDK 同一层的接口交互。快速开始获取 REST 客户端使用方式非常直接先创建一个opik.Opik()实例再通过rest_client属性访问底层客户端import opik # 初始化 Opik 客户端 client opik.Opik() # 通过 rest_client 属性访问 REST API rest_client client.rest_clientopik.Opik()在初始化时会根据环境配置如OPIK_API_KEY、OPIK_BASE_URL、OPIK_WORKSPACE等自动构建底层的OpikApi实例。你也可以直接实例化OpikApi并显式传参详见下文构造参数与高级配置一节。客户端结构全览OpikApi客户端以子客户端的形式组织接口每个子客户端对应一类平台资源。从 rest_api/client.py 的初始化代码可见当前版本包含部分列举子客户端对应资源tracesTrace 的查询、搜索、删除、评论、反馈分数spansSpan 的增删查改与反馈分数datasets数据集及其条目的增删查改、CSV/JSON 导入experiments实验与实验条目的创建、查询projects项目管理promptsPrompt 管理与版本获取environments环境管理feedback_definitions反馈分数定义annotation_queues标注队列attachments附件上传guardrails/automation_rule_evaluators护栏与自动化评估规则chat_completions/ollama/llm_provider_key模型推理与 Provider 密钥管理open_telemetry_ingestionOpenTelemetry 数据接入dashboards/system_usage/alerts/optimizations等仪表盘、用量、告警、优化等扩展能力每个子客户端如TracesClient还提供一个with_raw_response属性返回对应的原始响应客户端RawTracesClient用于需要直接获取 HTTP 响应头、原始状态码等场景顶级OpikApi同样提供with_raw_response返回RawOpikApi以及is_alive()与version()两个全局方法可用于健康检查与版本探测见 client.py。完整的客户端目录结构参见 rest_api/client.py 及其同级目录各模块的详细 API 文档见 rest_api/clients 目录。实战示例操作 Traces按 ID 获取单条 Trace# 获取指定 trace trace client.rest_client.traces.get_trace_by_id(trace-id)带过滤器搜索 Traces# 使用过滤器搜索 traces traces client.rest_client.traces.search_traces( project_namemy-project, filters[{ field: name, operator: contains, value: important }], max_results100 )filters列表中的每个过滤条件由field字段名、operator算子与value取值三元组构成。算子方面search_traces的底层实现支持contains、equals、not_equals、starts_with、ends_with、greater_than、less_than等具体算子集合以 traces 客户端文档 与后端过滤实现为准。project_name用于限定项目范围max_results控制返回上限。除上述两个方法外TracesClient还提供delete_traces批量删除、add_trace_comment、update_trace、get_trace_feedback_scores等能力完整方法清单见 traces/client.py。实战示例管理 Datasets分页列出数据集# 列出所有数据集 datasets client.rest_client.datasets.find_datasets( page0, size20 )创建数据集# 创建新数据集 dataset client.rest_client.datasets.create_dataset( namemy-dataset, descriptionA test dataset )批量写入数据集条目# 向数据集添加条目 items [ { input: {question: What is AI?}, expected_output: {answer: Artificial Intelligence} } ] client.rest_client.datasets.create_or_update_dataset_items( dataset_iddataset.id, itemsitems )值得注意create_or_update_dataset_items采用 upsert 语义条目中的id若已存在则更新否则创建。另外DatasetsClient还提供create_dataset_items_from_csv与create_dataset_items_from_json见 datasets/client.py可以直接从文件导入条目适合大批量数据灌入场景。实战示例运行 Experiments创建实验# 创建实验 experiment client.rest_client.experiments.create_experiment( namemy-experiment, dataset_namemy-dataset )写入实验结果# 添加实验结果 client.rest_client.experiments.create_experiment_items( experiment_idexperiment.id, items[{ dataset_item_id: item-id, trace_id: trace-id, output: {result: success} }] )实验条目通过dataset_item_id关联数据集中的样本通过trace_id关联实际运行产生的 Traceoutput记录模型的输出结果供后续评估与对比分析使用。响应类型与分页大多数列表操作返回分页结果且结构保持一致。以find_datasets为例# 分页响应结构示例 response client.rest_client.datasets.find_datasets(page0, size10) # 访问数据 datasets response.content # 数据集对象列表 total_count response.total # 条目总数 current_page response.page # 当前页码 page_size response.size # 每页条目数分页字段语义content当前页的数据对象列表遍历它即可处理本页结果total满足条件的条目总数用于计算总页数或展示统计page当前页码从 0 开始size每页条目数即请求时传入的size参数。分页遍历的通用写法如下page, size 0, 50 while True: response client.rest_client.datasets.find_datasets(pagepage, sizesize) for item in response.content: process(item) if page * size len(response.content) response.total: break page 1需要注意分页字段的确切命名page、size、total、content以各接口返回类型为准个别接口可能使用不同字段名上文为官方文档明确给出的通用结构。错误处理REST 客户端在请求失败时会抛出特定异常基类为ApiError。官方文档给出的统一捕获方式如下from opik.rest_api.core.api_error import ApiError try: trace client.rest_client.traces.get_trace_by_id(invalid-id) except ApiError as e: if e.status_code 404: print(Trace not found) else: print(fAPI error: {e.status_code} - {e.body})ApiError的关键属性status_codeHTTP 状态码可用于判断错误类型404 表示资源不存在401 表示未授权429 表示限流等body服务端返回的错误响应体通常包含更详细的错误信息。除通用ApiError外rest_api/errors 模块 还按 HTTP 语义细分了多种具体异常类型可直接按需捕获异常类对应 HTTP 状态BadRequestError400UnauthorizedError401ForbiddenError403NotFoundError404ConflictError409GoneError410UnprocessableEntityError422TooManyRequestsError429InternalServerError500BadGatewayError502ServiceUnavailableError503NotImplementedError501例如只关心资源不存在时可以精确捕获NotFoundError而无需判断status_code。构造参数与高级配置虽然通常通过opik.Opik().rest_client间接使用但OpikApi也可直接实例化并支持以下构造参数见 rest_api/client.py参数类型说明base_urlstr | None请求的基础 URL显式指定后优先于environmentenvironmentOpikApiEnvironment预设环境默认OpikApiEnvironment.DEFAULTapi_keystr | NoneAPI 密钥workspace_namestr | None工作区名称timeoutfloat | None请求超时秒默认 60 秒若传入自定义 httpx 客户端则以其超时为准follow_redirectsbool | None默认 httpx 客户端是否跟随重定向默认True传入自定义客户端时无效httpx_clienthttpx.Client | None自定义 httpx 客户端可用于配置代理、连接池、TLS 等高级需求from opik.rest_api import OpikApi client OpikApi( api_keyYOUR_API_KEY, workspace_nameYOUR_WORKSPACE_NAME, timeout30.0, )异步版本对于需要高并发的场景rest_api/client.py 还提供了AsyncOpikApi其子客户端全部为异步实现如AsyncTracesClient与httpx.AsyncClient配合使用from opik.rest_api import AsyncOpikApi import asyncio async def main(): client AsyncOpikApi(api_keyYOUR_API_KEY, workspace_nameYOUR_WORKSPACE_NAME) await client.traces.get_trace_by_id(trace-id) await client.is_alive() asyncio.run(main())下一步学习查看 REST API 客户端参考获取各资源模块traces、datasets、experiments、projects、prompts 等的详细方法文档查看 数据类型文档了解各接口返回的数据对象结构阅读主 SDK 文档了解更高层的封装操作大多数场景仍应优先使用高层 API仅在需要原始能力时再下沉到rest_client需要深入了解实现时可直接阅读 rest_api/client.py 及各子客户端源码或参考 overview.rst 原文。【免费下载链接】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），仅供参考 Opik Python SDK REST API 指南：通过 `rest_client` 直接调用平台底层接口
Opik Python SDK REST API 指南通过rest_client直接调用平台底层接口【免费下载链接】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 Python SDK 的 REST API 客户端能力如何通过opik.Opik()实例上的rest_client属性直接调用 Opik 平台的全部底层 HTTP 接口完成高级过滤查询、批量操作、自定义集成等高层 SDK 未覆盖的操作。读完本文你将掌握rest_client的获取方式、Traces/Datasets/Experiments 三大高频场景的调用模式、分页响应结构与异常处理策略并能结合源码理解其与高层 SDK 的关系及兼容性边界。什么是rest_clientOpik 的高层 Python SDK 封装了大多数日常操作打点追踪、数据集管理、实验评估等但它并不是平台能力的全集。为此SDK 在客户端对象上暴露了一个rest_client属性直接指向底层 REST API 客户端让进阶用户可以在需要时绕过高层封装直接发起 API 调用从而获得 Opik 平台全部功能的访问权限。在源码中该属性的定义位于 opik_client.py其返回类型为rest_api_client.OpikApi即 Fern 根据 Opik 的 API 定义自动生成的客户端类定义于 rest_api/client.py。[!WARNING]兼容性警告REST 客户端不保证与未来 SDK 版本向后兼容。它提供了一种便捷方式使用 Opik 当前的 REST API但由于 Opik 的 REST API 契约可能发生变化不建议重度依赖其接口。如果你的代码直接调用rest_client在升级 SDK 后需要重新验证相关调用。何时使用 REST API根据官方文档overview.rst当你遇到以下场景时REST API 客户端尤其有用执行高层 SDK 未提供的操作例如批量删除、按环境管理、直接读取原始返回值等构建自定义集成或工具将 Opik 能力嵌入自己的脚本、CLI 或平台使用高级过滤与查询能力REST API 暴露了完整的过滤算子可组合出复杂查询条件实现批量操作以提升性能例如批量写入数据集条目、批量删除 Traces处理特定用例所需的原始 API 响应高层 SDK 通常会做类型转换与封装REST 客户端可以拿到更贴近接口的原始结构。此外从源码看Opik 高层 SDK 自身的许多功能也正是通过rest_client实现的——例如 opik_client.py 中批量删除 Traces 使用self._rest_client.traces.delete_traces(idsbatch)环境管理使用self._rest_client.environments.*系列方法数据集查询也经由self._rest_client.datasets.get_dataset_by_identifier(...)见 opik_client.py。这意味着你直接使用rest_client时实际上是在与高层 SDK 同一层的接口交互。快速开始获取 REST 客户端使用方式非常直接先创建一个opik.Opik()实例再通过rest_client属性访问底层客户端import opik # 初始化 Opik 客户端 client opik.Opik() # 通过 rest_client 属性访问 REST API rest_client client.rest_clientopik.Opik()在初始化时会根据环境配置如OPIK_API_KEY、OPIK_BASE_URL、OPIK_WORKSPACE等自动构建底层的OpikApi实例。你也可以直接实例化OpikApi并显式传参详见下文构造参数与高级配置一节。客户端结构全览OpikApi客户端以子客户端的形式组织接口每个子客户端对应一类平台资源。从 rest_api/client.py 的初始化代码可见当前版本包含部分列举子客户端对应资源tracesTrace 的查询、搜索、删除、评论、反馈分数spansSpan 的增删查改与反馈分数datasets数据集及其条目的增删查改、CSV/JSON 导入experiments实验与实验条目的创建、查询projects项目管理promptsPrompt 管理与版本获取environments环境管理feedback_definitions反馈分数定义annotation_queues标注队列attachments附件上传guardrails/automation_rule_evaluators护栏与自动化评估规则chat_completions/ollama/llm_provider_key模型推理与 Provider 密钥管理open_telemetry_ingestionOpenTelemetry 数据接入dashboards/system_usage/alerts/optimizations等仪表盘、用量、告警、优化等扩展能力每个子客户端如TracesClient还提供一个with_raw_response属性返回对应的原始响应客户端RawTracesClient用于需要直接获取 HTTP 响应头、原始状态码等场景顶级OpikApi同样提供with_raw_response返回RawOpikApi以及is_alive()与version()两个全局方法可用于健康检查与版本探测见 client.py。完整的客户端目录结构参见 rest_api/client.py 及其同级目录各模块的详细 API 文档见 rest_api/clients 目录。实战示例操作 Traces按 ID 获取单条 Trace# 获取指定 trace trace client.rest_client.traces.get_trace_by_id(trace-id)带过滤器搜索 Traces# 使用过滤器搜索 traces traces client.rest_client.traces.search_traces( project_namemy-project, filters[{ field: name, operator: contains, value: important }], max_results100 )filters列表中的每个过滤条件由field字段名、operator算子与value取值三元组构成。算子方面search_traces的底层实现支持contains、equals、not_equals、starts_with、ends_with、greater_than、less_than等具体算子集合以 traces 客户端文档 与后端过滤实现为准。project_name用于限定项目范围max_results控制返回上限。除上述两个方法外TracesClient还提供delete_traces批量删除、add_trace_comment、update_trace、get_trace_feedback_scores等能力完整方法清单见 traces/client.py。实战示例管理 Datasets分页列出数据集# 列出所有数据集 datasets client.rest_client.datasets.find_datasets( page0, size20 )创建数据集# 创建新数据集 dataset client.rest_client.datasets.create_dataset( namemy-dataset, descriptionA test dataset )批量写入数据集条目# 向数据集添加条目 items [ { input: {question: What is AI?}, expected_output: {answer: Artificial Intelligence} } ] client.rest_client.datasets.create_or_update_dataset_items( dataset_iddataset.id, itemsitems )值得注意create_or_update_dataset_items采用 upsert 语义条目中的id若已存在则更新否则创建。另外DatasetsClient还提供create_dataset_items_from_csv与create_dataset_items_from_json见 datasets/client.py可以直接从文件导入条目适合大批量数据灌入场景。实战示例运行 Experiments创建实验# 创建实验 experiment client.rest_client.experiments.create_experiment( namemy-experiment, dataset_namemy-dataset )写入实验结果# 添加实验结果 client.rest_client.experiments.create_experiment_items( experiment_idexperiment.id, items[{ dataset_item_id: item-id, trace_id: trace-id, output: {result: success} }] )实验条目通过dataset_item_id关联数据集中的样本通过trace_id关联实际运行产生的 Traceoutput记录模型的输出结果供后续评估与对比分析使用。响应类型与分页大多数列表操作返回分页结果且结构保持一致。以find_datasets为例# 分页响应结构示例 response client.rest_client.datasets.find_datasets(page0, size10) # 访问数据 datasets response.content # 数据集对象列表 total_count response.total # 条目总数 current_page response.page # 当前页码 page_size response.size # 每页条目数分页字段语义content当前页的数据对象列表遍历它即可处理本页结果total满足条件的条目总数用于计算总页数或展示统计page当前页码从 0 开始size每页条目数即请求时传入的size参数。分页遍历的通用写法如下page, size 0, 50 while True: response client.rest_client.datasets.find_datasets(pagepage, sizesize) for item in response.content: process(item) if page * size len(response.content) response.total: break page 1需要注意分页字段的确切命名page、size、total、content以各接口返回类型为准个别接口可能使用不同字段名上文为官方文档明确给出的通用结构。错误处理REST 客户端在请求失败时会抛出特定异常基类为ApiError。官方文档给出的统一捕获方式如下from opik.rest_api.core.api_error import ApiError try: trace client.rest_client.traces.get_trace_by_id(invalid-id) except ApiError as e: if e.status_code 404: print(Trace not found) else: print(fAPI error: {e.status_code} - {e.body})ApiError的关键属性status_codeHTTP 状态码可用于判断错误类型404 表示资源不存在401 表示未授权429 表示限流等body服务端返回的错误响应体通常包含更详细的错误信息。除通用ApiError外rest_api/errors 模块 还按 HTTP 语义细分了多种具体异常类型可直接按需捕获异常类对应 HTTP 状态BadRequestError400UnauthorizedError401ForbiddenError403NotFoundError404ConflictError409GoneError410UnprocessableEntityError422TooManyRequestsError429InternalServerError500BadGatewayError502ServiceUnavailableError503NotImplementedError501例如只关心资源不存在时可以精确捕获NotFoundError而无需判断status_code。构造参数与高级配置虽然通常通过opik.Opik().rest_client间接使用但OpikApi也可直接实例化并支持以下构造参数见 rest_api/client.py参数类型说明base_urlstr | None请求的基础 URL显式指定后优先于environmentenvironmentOpikApiEnvironment预设环境默认OpikApiEnvironment.DEFAULTapi_keystr | NoneAPI 密钥workspace_namestr | None工作区名称timeoutfloat | None请求超时秒默认 60 秒若传入自定义 httpx 客户端则以其超时为准follow_redirectsbool | None默认 httpx 客户端是否跟随重定向默认True传入自定义客户端时无效httpx_clienthttpx.Client | None自定义 httpx 客户端可用于配置代理、连接池、TLS 等高级需求from opik.rest_api import OpikApi client OpikApi( api_keyYOUR_API_KEY, workspace_nameYOUR_WORKSPACE_NAME, timeout30.0, )异步版本对于需要高并发的场景rest_api/client.py 还提供了AsyncOpikApi其子客户端全部为异步实现如AsyncTracesClient与httpx.AsyncClient配合使用from opik.rest_api import AsyncOpikApi import asyncio async def main(): client AsyncOpikApi(api_keyYOUR_API_KEY, workspace_nameYOUR_WORKSPACE_NAME) await client.traces.get_trace_by_id(trace-id) await client.is_alive() asyncio.run(main())下一步学习查看 REST API 客户端参考获取各资源模块traces、datasets、experiments、projects、prompts 等的详细方法文档查看 数据类型文档了解各接口返回的数据对象结构阅读主 SDK 文档了解更高层的封装操作大多数场景仍应优先使用高层 API仅在需要原始能力时再下沉到rest_client需要深入了解实现时可直接阅读 rest_api/client.py 及各子客户端源码或参考 overview.rst 原文。【免费下载链接】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），仅供参考