实验执行、并发、重试与多模态

指标返回契约

• numerical metric：Python 可直接返回 int/float/bool，跨语言稳定形式为 {key, score}。
• categorical metric：Python 可直接返回字符串，跨语言稳定形式为 {key, value}。
• 一个 evaluator 可一次返回多项指标，复用同一次 judge 调用以降低成本；Python 返回结果列表，TypeScript 返回带 results 的对象。
• 多指标支持基线：Python langsmith>=0.2.0，TypeScript langsmith>=0.1.32。

metric key 是长期分析契约。改名、改变量纲或把 categorical 改成 numerical 会破坏历史可比性，应像 API/schema 变更一样版本化。

Repetition、concurrency 与 cache

num_repetitions=N 会对每个 Example 重跑 target 和全部 evaluators；5 个样本、5 次 repetition 即 25 个 runs。UI 展示平均分，也可查看单次分数和标准差。它用于估计非确定性，不是通过重复运行“挑最好一次”。

max_concurrency 在同步 evaluate 中限制 target/evaluator 工作线程，在 aevaluate 中用 semaphore 限制同时处理的 examples。值过高会放大 provider 限流、连接池、费用和下游副作用；值过低会拖慢 CI。应按最小 provider 配额与最慢依赖调优。

LANGSMITH_TEST_CACHE 指向可写目录后，相同 API 调用可复用磁盘结果。缓存适合 prompt/evaluator 调试，但发布基准必须记录是否启用、cache key 涵盖哪些参数，并定期用冷缓存验证，避免旧响应掩盖模型变化。

限流与失败恢复

推荐组合：provider-aware rate limiter → 有上限的指数退避 + jitter → 限制 max_concurrency → 只重试可恢复错误。重试必须设置最大次数/总时限，外部有副作用的 target 还要有幂等键。

Python 可用 error_handling='ignore' 跳过失败 run 的记录，再通过 experiment 已成功的 reference_example_id 找出缺失 examples，把失败子集重新写入同一 experiment。这里“缺失即失败”只有在每个 example 应恰好产生 run 时成立；并发重复、取消和数据版本变化必须单独审计。

已存在 experiment 可以只新增 evaluators，不重跑 target（当前仅 Python SDK）；dataset 绑定 evaluator 只影响绑定后创建的新 experiment runs，不会回填旧数据。两者解决的问题不同。

本地与 CI 结果

• upload_results=False（Python）让 target 和 evaluators 完全本地运行，应用/evaluator traces 也不上传，适合 smoke test。
• 正常上传时，ExperimentResults 仍可在本地迭代；blocking=False 边运行边产出，blocking=True 等待完整数据后再做 percentile、排序或汇总。
• 每项结果包含 target run、evaluation results 和 Example；CI 可按阈值退出非零，但阈值应同时考虑样本量、方差和关键分组，不能只看全局平均。

多模态附件

附件比 base64 更省传输和存储，可用于图像、音频、PDF 等 dataset examples，并传给 target/evaluator。UI 单附件上限为 20MB；2026-08-11 文档要求 Python langsmith>=0.3.13、TypeScript >=0.2.13。

关键差异：

• Python create_examples/update_examples 支持 attachment；若从本地路径读取必须显式 dangerously_allow_filesystem=True。
• TypeScript 使用 uploadExamplesMultipart/updateExamplesMultipart，标准 createExamples 当前不支持附件；数据为 Uint8Array 或 ArrayBuffer，不能直接传本地路径。
• Python target 若消费附件，位置参数必须依次命名为 inputs、attachments；TypeScript 通过启用 includeAttachments 后的 config 获取。
• UI evaluator 的模型必须同时支持输入模态和 structured output；文档当前指出音频附件只有 Gemini，图像/PDF 可用支持 structured output 的 vision model。
• 更新 attachment 时，未显式 retain/rename 的已有附件会被删除；新附件与旧附件重名时新值优先。

附件可能包含隐私、恶意 PDF/图片或超大解压内容。评估 worker 应限制 MIME、大小、解码资源和网络访问；presigned URL 不进入日志，dangerously_allow_filesystem 只对受控路径开启。

版本与费用边界

一次可重现的 experiment 至少记录：dataset version/tag、target commit、prompt/model/provider 版本、evaluator 版本、metric schema、repetitions、concurrency、cache、失败/重试策略与附件版本。缺少其中任一项，都可能让“分数变化”无法归因。