企业官网建设流程全解析

Opik Python SDK 中的 RedirectClient 使用指南：为 SDK 生成链接创建平台内重定向

【免费下载链接】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_client.redirect（即RedirectClient）提供了一组用于生成平台内 URL 重定向的接口，其作用是让 SDK 生成的 trace、dataset、experiment、optimization 链接能够携带鉴权上下文并跳转到 Opik 前端对应的详情页面。本文基于 redirect.rst 文档，并结合 SDK 与后端源码，完整讲解 RedirectClient 的四个方法、参数语义、Base64URL 编码机制以及后端的 303 重定向实现。

RedirectClient 是什么

根据文档定义，Redirect Client 为 Opik 平台提供处理 URL 重定向的方法（"The Redirect client provides methods for handling URL redirects in the Opik platform"）。它的典型应用场景是：当你在命令行、Notebook 或 CI 脚本中通过 SDK 创建了 trace、dataset、experiment 或优化任务后，SDK 无法直接把未经验证的深链交给用户；通过 RedirectClient 请求后端，后端会校验资源归属、解析出正确的工作区与资源 ID，再返回一个可直达前端页面的 303 重定向。

在 SDK 代码中，RedirectClient定义于 sdks/python/src/opik/rest_api/redirect/client.py，并由聚合客户端OpikApi在 sdks/python/src/opik/rest_api/client.py 中挂载为self.redirect属性。日常使用时，通过opik.Opik()客户端暴露的rest_client属性即可访问（见 sdks/python/src/opik/api_objects/opik_client.py 中rest_client属性返回OpikApi实例的实现）。

快速上手：最小可用示例

文档给出的示例展示了从opik.Opik()客户端进入 Redirect 模块的基本形态：

import opik client = opik.Opik() # 处理重定向操作 result = client.rest_client.redirect.datasets_redirect( dataset_id="dataset_id", path="cGF0aA==", )

需要特别说明：该文档页面的示例代码仅为示意性写法，实际可调用的方法名以源码为准。RedirectClient真实提供四个方法，且path参数要求传入 Base64 URL 编码后的字符串（详见下文"path 参数的编码机制"），方法调用成功后返回None，重定向动作由后端以 303 响应完成。

四个核心方法及其参数

RedirectClient（同步）与AsyncRedirectClient（异步）各提供四个方法，方法名与后端 REST 端点一一对应（端点定义见 sdks/python/src/opik/rest_api/redirect/raw_client.py）：

所有方法均支持两个可选参数：

• workspace_name: Optional[str]：目标工作区名称。传参会跳过后端按资源 ID 反查工作区的步骤；不传时后端会依据资源所属的 workspace 自动解析。
• request_options: Optional[RequestOptions]：请求级配置，可用于设置超时、附加头信息等。

各方法调用示例

数据集重定向：

from Opik import OpikApi client = OpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME") client.redirect.datasets_redirect( dataset_id="8f2e4a5b-0000-0000-0000-000000000001", path="aXRlbXM=", )

实验对比重定向（需要同时提供数据集 ID 与实验 ID）：

client.redirect.experiments_redirect( dataset_id="8f2e4a5b-0000-0000-0000-000000000001", experiment_id="8f2e4a5b-0000-0000-0000-000000000002", path="Y29tcGFyZQ==", )

优化任务对比重定向：

client.redirect.optimizations_redirect( dataset_id="8f2e4a5b-0000-0000-0000-000000000001", optimization_id="8f2e4a5b-0000-0000-0000-000000000003", path="Y29tcGFyZQ==", )

项目 trace 重定向（以 trace_id 定位项目）：

client.redirect.projects_redirect( trace_id="8f2e4a5b-0000-0000-0000-000000000004", path="dHJhY2Vz", )

异步客户端 AsyncRedirectClient

当你的应用基于asyncio时，可使用AsyncRedirectClient，四个方法的签名与同步版完全一致，只是调用时需要await。参考 client.py 中生成的 docstring 示例：

import asyncio from Opik import AsyncOpikApi client = AsyncOpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME") async def main() -> None: await client.redirect.datasets_redirect( dataset_id="8f2e4a5b-0000-0000-0000-000000000001", path="aXRlbXM=", ) asyncio.run(main())

同步与异步客户端都通过with_raw_response属性暴露底层RawRedirectClient/AsyncRawRedirectClient，后者返回完整的HttpResponse[None]对象，便于需要访问原始响应头或状态码的进阶场景。文档中的:exclude-members: with_raw_response指令正是为了在 API 文档中隐藏这一进阶属性，保持页面聚焦于常规用法。

path 参数的编码机制

path并非任意的前端路由字符串，而是需要经过Base64 URL 编码（RFC 4648 的 URL-safe 变体，即使用-与_而非+与/，且不带 padding）后的值。这一点可以从后端实现得到确认：

在 apps/opik-backend/src/main/java/com/comet/opik/api/resources/v1/session/RedirectResource.java 中，四个端点收到path参数后统一执行：

new String(Base64.getUrlDecoder().decode(path), StandardCharsets.UTF_8)

即在服务端用Base64.getUrlDecoder()解码后再拼接前端 URL。因此，SDK 侧在发起请求前，应先将想要跳转的前端路径（如"items"、"compare"、"traces"）做 URL-safe Base64 编码，再作为path传入。例如 Python 中：

import base64 path = base64.urlsafe_b64encode(b"items").rstrip(b"=").decode() # path == "aXRlbXM"

后端随后通过 303 See Other 状态码（Response.seeOther(...)）将请求重定向到真实前端地址。

后端如何组装重定向 URL

重定向 URL 的组装逻辑位于 apps/opik-backend/src/main/java/com/comet/opik/domain/RedirectService.java 的RedirectServiceImpl，其内部定义了四条前端 URL 模板：

private static final String TRACE_REDIRECT_URL = "%s/%s/projects/%s/traces?tab=logs&logsType=traces&trace=%s"; private static final String DATASET_REDIRECT_URL = "%s/%s/datasets/%s/items"; private static final String EXPERIMENT_REDIRECT_URL = "%s/%s/experiments/%s/compare?experiments=%s"; private static final String OPTIMIZATION_REDIRECT_URL = "%s/%s/optimizations/%s/compare?optimizations=%s";

组装过程的关键步骤：

1. 解析工作区：若请求未携带workspace_name，projectsRedirect通过traceService.getTraceDetailsById(traceId)拿到 trace 的 workspaceId 与 projectId，再由workspaceNameService.getWorkspaceName(...)反查工作区名；数据集类端点则通过datasetService.findWorkspaceIdByDatasetId(datasetId)完成同样的反查。
2. 解析前端地址：feBaseUrl(opikBEBaseUrl)会从后端地址中截取/api之前的部分作为前端基地址（若地址不含/api会抛出RuntimeException）。
3. 拼接资源 ID：experiments与optimizations的 ID 会被包装成 JSON 数组形式（["<id>"]）并用URLEncoder.encode转义后放入查询参数，以适配前端对比页的多选参数格式。

错误处理与请求细节

从 raw_client.py 可以看到，四个请求均通过httpx客户端以GET方式发出，workspace_name以查询参数随请求传递。响应处理遵循以下规则：

• 2xx 状态码：返回HttpResponse[None]，业务上重定向已由服务端完成；
• 400：抛出BadRequestError（如dataset_id等参数缺失或格式非法）；
• 404：抛出NotFoundError（如对应 trace、dataset 资源不存在）；
• 其他状态码或响应体无法解析为 JSON：抛出ApiError，携带原始状态码、响应头与响应文本。

因此调用方应当对这三类异常做捕获处理，特别是在资源 ID 由用户输入或历史数据提供时：

from Opik.core.api_error import ApiError from Opik.errors import NotFoundError, BadRequestError try: client.redirect.projects_redirect( trace_id="8f2e4a5b-0000-0000-0000-000000000004", path=base64.urlsafe_b64encode(b"traces").rstrip(b"=").decode(), ) except BadRequestError: print("参数不合法") except NotFoundError: print("trace 不存在") except ApiError as e: print(f"请求失败: {e.status_code}")

典型使用场景

• CI 报告输出：在自动化评估流水线结束后，用experiments_redirect生成实验对比页链接，写入测试报告或 IM 通知；
• CLI 工具深链：命令行工具创建数据集后，用datasets_redirect输出直达数据集 items 页的链接，用户点击即可进入前端继续标注或浏览；
• 优化任务跟进：运行 Prompt 优化后，用optimizations_redirect将优化对比结果页分享给团队；
• 调试追溯：用projects_redirect把某条 trace 的具体详情页（含日志标签页）直接发给协作者。

参考源码路径

• SDK 文档页面：apps/opik-documentation/python-sdk-docs/source/rest_api/clients/redirect.rst
• 客户端实现（同步/异步）：sdks/python/src/opik/rest_api/redirect/client.py
• 底层 HTTP 实现： sdks/python/src/opik/rest_api/redirect/raw_client.py
• 聚合 REST 客户端挂载： sdks/python/src/opik/rest_api/client.py
• 后端 REST 端点：apps/opik-backend/src/main/java/com/comet/opik/api/resources/v1/session/RedirectResource.java
• 后端 URL 组装服务：apps/opik-backend/src/main/java/com/comet/opik/domain/RedirectService.java

【免费下载链接】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