Opik Python SDK Automation Rule Evaluators REST 客户端详解以编程方式管理自动化评估规则【免费下载链接】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 仓库中 Automation Rule Evaluators 文档页 与当前 Python SDK 的生成客户端源码展开讲清楚AutomationRuleEvaluatorsClient提供哪些方法、每个方法对应的 HTTP 端点与参数、请求/响应数据模型判别联合类型、sampling_rate、trigger_scope等关键字段以及同步/异步、原始响应三种使用形态帮助你在脚本或自动化流水线中批量创建、查询、更新、删除 Opik 平台的在线评估规则Automation Rule Evaluators并审计其执行日志。一、背景Automation Rule Evaluators 是什么Automation Rule Evaluators 是 Opik 平台的在线评估规则为项目project配置一条规则后平台会对符合条件的 trace / span / thread 数据自动运行评估器LLM-as-judge 或用户自定义 Python 指标把分数写回平台实现无需离线实验的持续质量监控。从当前 SDK 的类型定义看一个规则由两部分构成公共字段Basename必填、project_id旧版单项目字段、project_ids多项目支持的新字段、sampling_rate、enabled、trigger_scope见 automation_rule_evaluator_write.py判别联合discriminated union按type字段区分的 6 种评估器类型每类带有自己的filters和code结构。6 种类型及其语义源自 automation_rule_evaluator_write.pytype取值评估对象评估器种类llm_as_judgetraceLLM 裁判提示词 模型打分user_defined_metric_pythontrace用户自定义 Python 指标代码trace_thread_llm_as_judgethread线程/会话LLM 裁判trace_thread_user_defined_metric_pythonthread用户自定义 Python 指标代码span_llm_as_judgespanLLM 裁判span_user_defined_metric_pythonspan用户自定义 Python 指标代码公共字段中几个容易踩坑的语义直接引自源码 docstringsampling_rate0 到 1 之间的浮点数表示该规则对生产SDK 上报数据的采样比例trace 规则对 experiment / playground / optimization 产生的 trace忽略该值并全量评分而 span 与 thread 规则只评估 SDK 上报的数据automation_rule_evaluator_write.py#L34-L37。trigger_scope取值为production、experiment、both三者的联合类型automation_rule_evaluator_write_trigger_scope.py控制规则在生产 trace、实验 trace 还是两者上触发省略时默认为production。project_id被标注为 Primary project ID (legacy field for backwards compatibility)多项目场景应使用project_ids。二、如何拿到客户端文档页给出的入口是import opik client opik.Opik() # 该属性返回 OpikApi底层 REST 客户端 evaluators_client client.rest_client.automation_rule_evaluators源码可以印证这条链路Opik类的rest_client属性返回一个OpikApi实例见 opik_client.py#L169-L180Opik类定义于 opik_client.py#L108OpikApi在初始化时挂载各资源子客户端其中第 123 行即为self.automation_rule_evaluators AutomationRuleEvaluatorsClient(client_wrapperself._client_wrapper)见 rest_api/client.py#L123。因此client.rest_client.automation_rule_evaluators拿到的是 AutomationRuleEvaluatorsClient。需要说明该客户端文件头部标注This file was auto-generated by Fern from our API Definition即由 OpenAPI 定义经 Fern 生成仓库中生成配置位于 sdks/code_generation/fern。三、方法总览与对应 HTTP 端点AutomationRuleEvaluatorsClient共提供 6 个业务方法。端点信息来自 raw_client.py该文件同时包含同步RawAutomationRuleEvaluatorsClient与异步AsyncRawAutomationRuleEvaluatorsClient两套实现方法HTTP 方法与路径返回类型find_evaluatorsGET v1/private/automations/evaluatorsAutomationRuleEvaluatorPagePubliccreate_automation_rule_evaluatorPOST v1/private/automations/evaluatorsNonedelete_automation_rule_evaluator_batchPOST v1/private/automations/evaluators/deleteNoneget_evaluator_by_idGET v1/private/automations/evaluators/{id}AutomationRuleEvaluatorPublicupdate_automation_rule_evaluatorPATCH v1/private/automations/evaluators/{id}Noneget_evaluator_logs_by_idGET v1/private/automations/evaluators/{id}/logsLogPage所有方法均接受可选的request_options: RequestOptions参数请求级配置如超时、重试等这是 Fern 生成客户端的通用约定。四、逐方法详解4.1 列表查询find_evaluators签名client.py#L33-L44def find_evaluators( self, *, project_id: typing.Optional[str] None, id: typing.Optional[str] None, name: typing.Optional[str] None, filters: typing.Optional[str] None, sorting: typing.Optional[str] None, page: typing.Optional[int] None, size: typing.Optional[int] None, request_options: typing.Optional[RequestOptions] None, ) - AutomationRuleEvaluatorPagePublic:除request_options外全部为关键字参数且可选project_id、id、name为直查条件filters与sorting为字符串化的过滤/排序表达式page/size控制分页底层以 query 参数方式发送见 raw_client.py#L66-L79。响应模型 AutomationRuleEvaluatorPagePublic 包含page、size、total总数便于翻页判断、content当前页规则对象列表、sortable_by可排序字段提示。4.2 创建规则create_automation_rule_evaluatordef create_automation_rule_evaluator( self, *, request: AutomationRuleEvaluatorWrite, request_options: typing.Optional[RequestOptions] None ) - None:注意当前实现中创建方法只接受一个request参数其类型是 6 种评估器组成的判别联合automation_rule_evaluator_write.py#L147-L154。以 trace 级 LLM 裁判为例import opik from opik.rest_api import ( AutomationRuleEvaluatorWrite_LlmAsJudge, LlmAsJudgeCodeWrite, ) client opik.Opik() client.rest_client.automation_rule_evaluators.create_automation_rule_evaluator( requestAutomationRuleEvaluatorWrite_LlmAsJudge( project_idmy-project-id, # 或使用 project_ids[...] 绑定多个项目 nameproduction-hallucination-check, sampling_rate0.5, # 生产数据 50% 采样0~1 enabledTrue, trigger_scopeproduction, # 或 experiment / both缺省为 production # filters[...], # TraceFilterWrite 列表限定规则命中的 trace 子集 # codeLlmAsJudgeCodeWrite(...), # LLM 裁判的提示词/模型配置 ) )request会被序列化为 JSON 后POST序列化走convert_and_respect_annotation_metadata(object_request, annotationAutomationRuleEvaluatorWrite, directionwrite)raw_client.py#L112-L123。4.3 按 ID 查询get_evaluator_by_iddef get_evaluator_by_id( self, id: str, *, project_id: typing.Optional[str] None, request_options: typing.Optional[RequestOptions] None ) - AutomationRuleEvaluatorPublic:id是位置必填参数拼入路径v1/private/automations/evaluators/{id}raw_client.py#L202-L208。响应模型 AutomationRuleEvaluatorPublic 在写入模型公共字段的基础上额外返回审计与项目绑定信息id、name、sampling_rate、enabled、trigger_scope、actionprojectsProjectReferencePublic列表注释说明其唯一、按项目名字母序排序project_id/project_name为兼容旧版的单项目字段审计字段created_at、created_by、last_updated_at、last_updated_by。4.4 更新规则update_automation_rule_evaluatordef update_automation_rule_evaluator( self, id: str, *, request: AutomationRuleEvaluatorUpdate, request_options: typing.Optional[RequestOptions] None ) - None:请求体为AutomationRuleEvaluatorUpdate结构与 Write 版本对应6 种联合成员一致见 automation_rule_evaluator_update.py公共字段为name、sampling_rate、enabled、trigger_scope、project_id、project_ids、action。底层走PATCH v1/private/automations/evaluators/{id}raw_client.py#L248-L259。典型用法是只调整采样率或启停规则from opik.rest_api import AutomationRuleEvaluatorUpdate_UserDefinedMetricPython client.rest_client.automation_rule_evaluators.update_automation_rule_evaluator( idevaluator-id, requestAutomationRuleEvaluatorUpdate_UserDefinedMetricPython( namemy-evaluator, sampling_rate0.1, enabledFalse, ), )4.5 批量删除delete_automation_rule_evaluator_batchdef delete_automation_rule_evaluator_batch( self, *, ids: typing.Sequence[str], project_id: typing.Optional[str] None, request_options: typing.Optional[RequestOptions] None, ) - None:ids为字符串序列放入请求体{ids: [...]}project_id作为 query 参数raw_client.py#L155-L169。4.6 查询执行日志get_evaluator_logs_by_iddef get_evaluator_logs_by_id( self, id: str, *, size: typing.Optional[int] None, request_options: typing.Optional[RequestOptions] None ) - LogPage:访问v1/private/automations/evaluators/{id}/logs用size控制单次拉取的日志条数。返回 LogPagecontentLogItem列表、page、size、total。这是排查规则到底跑没跑、跑了什么、失败在哪的主要入口。五、文档页原始示例的对照说明文档页给出的 Usage Example 如下完整继承自 automation_rule_evaluators.rst 的用法章节import opik client opik.Opik() # List automation rule evaluators evaluators client.rest_client.automation_rule_evaluators.find_automation_rule_evaluators( page0, size10 ) # Get an evaluator by ID evaluator client.rest_client.automation_rule_evaluators.get_automation_rule_evaluator_by_id( evaluator-id ) # Create a new evaluator client.rest_client.automation_rule_evaluators.create_automation_rule_evaluator( namemy-evaluator, project_idproject-id, codedef evaluate(trace): return {score: 0.8} )对照当前仓库源码示例体现的列表 / 按 ID 获取 / 创建三段式用法与现有实现一一对应但方法名与入参形态已演进落地时应以源码为准文档示例写法当前源码对应实现find_automation_rule_evaluators(page0, size10)find_evaluators(page0, size10)另支持project_id/id/name/filters/sortingget_automation_rule_evaluator_by_id(evaluator-id)get_evaluator_by_id(evaluator-id, project_id...)create_automation_rule_evaluator(name..., project_id..., code...)create_automation_rule_evaluator(request...)request为带type判别字段的 Pydantic 联合对象也就是说文档示例中把code作为裸字符串直接传入的简化写法在当前类型系统里被显式的LlmAsJudgeCodeWrite/UserDefinedMetricPythonCodeWrite等code结构体取代创建时必须先选定 6 种type之一。这属于 API 文档快照与生成代码之间的版本差异建议以 automation_rule_evaluators/client.py 的实际签名为准。六、异步与原始响应两种形态异步客户端AsyncAutomationRuleEvaluatorsClient 提供与同步版本完全同构的 6 个async def方法挂载在AsyncOpikApi.automation_rule_evaluatorsrest_api/client.py#L278适合在高并发采集/管理场景中await调用。原始响应AutomationRuleEvaluatorsClient上的with_raw_response属性client.py#L22-L31返回RawAutomationRuleEvaluatorsClient其方法直接返回HttpResponse[T]包装含status_code、headers与解析后的data。文档页的 autoclass 指令用:exclude-members: with_raw_response在渲染时排除了它但运行时代码中该属性依然存在可用于需要读取响应头如分页元信息、限流提示的场景。七、实现细节错误处理与序列化阅读 raw_client.py 可以确认生成客户端的统一处理模式每个方法先通过self._client_wrapper.httpx_client.request(...)发起 httpx 请求URL 中的id经jsonable_encoder转义2xx响应用parse_obj_as(type_..., object__response.json())反序列化为对应 Pydantic 模型如AutomationRuleEvaluatorPagePublic、LogPage后返回非 2xx 或响应体 JSON 解析失败抛出ApiError(status_code..., headers..., body...)。因此调用侧只需针对ApiError捕获即可得到状态码与错误体写入请求体经convert_and_respect_annotation_metadata(..., directionwrite)序列化配合模块级哨兵OMIT处理可省略字段。八、进一步阅读客户端实现同步客户端、原始客户端与异步客户端数据模型Write 模型、Public 模型、Update 模型、分页模型、日志分页模型、触发范围客户端装配OpikApi 各子客户端挂载、Opik.rest_client 属性文档源文件automation_rule_evaluators.rst适用前提以上方法签名、字段语义与端点路径均以当前仓库中sdks/python下的生成代码为准由于该客户端由 OpenAPI 定义自动生成若后端 API 演进字段增删、方法重命名需以最新生成的代码为准。【免费下载链接】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），仅供参考