--- type: study created: 2026-08-11 updated: 2026-08-11 sensitivity: private status: active tags: - study - langsmith - evaluation - reliability - multimodal topic: LangSmith 实验配置、并发、重试、本地结果与多模态附件 sources: - https://docs.langchain.com/langsmith/multiple-scores - https://docs.langchain.com/langsmith/metric-type - https://docs.langchain.com/langsmith/experiment-configuration - https://docs.langchain.com/langsmith/evaluation-async - https://docs.langchain.com/langsmith/repetition - https://docs.langchain.com/langsmith/handle-model-rate-limiting - https://docs.langchain.com/langsmith/bind-evaluator-to-dataset-link - https://docs.langchain.com/langsmith/evaluate-existing-experiment - https://docs.langchain.com/langsmith/local - https://docs.langchain.com/langsmith/read-local-experiment-results - https://docs.langchain.com/langsmith/evaluate-with-retry - https://docs.langchain.com/langsmith/evaluate-with-attachments last_verified: 2026-08-11 --- # 实验执行、并发、重试与多模态 ## 指标返回契约 - 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、失败/重试策略与附件版本。缺少其中任一项，都可能让“分数变化”无法归因。