Bin✳

学习笔记 · Obsidian

Prompt 工程、版本治理与模型配置

LangChainLangSmith
来源更新 2026-08-11下载 Markdown ↓

Prompt 在 LangSmith 中是有 commit 的运行时依赖，不是一段随手复制的文本。生产调用应固定 commit 或受控 tag，变更必须经过评估、审批、推广和可回滚发布。

一、Prompt 资产模型

一个可运行 Prompt 通常包括：

  • system/user/assistant message templates。
  • input variables 与可选 examples。
  • tools/functions schema。
  • structured output schema。
  • 关联 model configuration 与调用参数。
  • owner、visibility、tags、commit history。

Prompt Hub/Context Hub 与代码仓库角色不同：它适合高频调整和跨职能协作，但不能省略代码审查、测试和发布治理。

二、Prompt 工程框架

高质量 prompt 应分清：

  1. 角色与目标。
  2. 权威数据和上下文。
  3. 必须遵守的约束。
  4. 可调用工具及何时调用。
  5. 输出 schema。
  6. 少样本示例与反例。
  7. 不确定/失败时的行为。

优化步骤：

  • 先定义离线数据集和指标。
  • 在 Playground 对同一输入比较 prompt/model。
  • 查看失败 trace，不只看平均分。
  • 一次只改一个主要变量。
  • 保存 commit，并把实验关联到 commit。
  • 通过 staging/灰度后再更新生产 tag。

“Write prompt with AI”与 Chat 可以生成、优化 prompt、tool 和 schema，但结果仍是候选变更，必须人工审查 prompt injection、权限、工具副作用和输出兼容性。

三、模板格式

LangSmith 当前支持：

格式语法适用
f-string单花括号变量平面数据、简单替换
Mustache双花括号变量嵌套数据、循环、条件、evaluator

f-string 是简化子集，不支持：

  • 点号访问嵌套对象。
  • 格式化 specifier。
  • 表达式、函数调用、条件/循环。
  • 数组索引。

字面花括号要转义。变量区分大小写。

Mustache 是 logic-less 模板，支持：

  • 点号访问嵌套对象。
  • section 遍历数组或按 truthy 渲染。
  • inverted section 表达空/false 分支。
  • 当前 item、注释、嵌套 section。

从 Mustache 转 f-string 只能覆盖简单替换；包含循环/条件时不可无损转换。生产中固定 template format，并用真实嵌套样本做渲染测试。

四、UI 与 SDK 生命周期

UI 可以创建、编辑、测试、保存 commit、打 tag 和管理 visibility。SDK 可以：

  • push prompt / structured prompt。
  • pull 指定 handle、commit 或 tag。
  • list、delete、like public prompts。
  • 将 Prompt 转为 OpenAI/Anthropic payload。

运行时建议：

  • 开发可拉 latest。
  • staging 拉 staging tag。
  • production 拉不可变 commit，或只通过审批流程移动 production tag。
  • trace metadata 记录 prompt handle、commit 和发布 tag。

若使用非 LangChain Provider SDK，转换方法仍依赖相应 LangChain integration package；要把它作为显式运行依赖管理。

五、Prompt pull cache

Python langsmith 0.7.0+、TypeScript 0.5.0+ 默认启用进程级全局 Prompt cache：

  • max size 100。
  • TTL 300 秒。
  • 每 60 秒检查 stale 并后台刷新。
  • stale-while-revalidate。

重要行为：

  • 全部 clients 共享 singleton。
  • 后台 refresh 使用最后请求该 prompt 的 client。
  • 可单次 skip cache、按 client/global 禁用。
  • 可 dump/load 支持离线；TTL 设无限时不启动刷新线程。
  • 进程结束可 stop refresh。

风险：

  • production tag 移动后最多在 TTL 内继续旧版本。
  • 多 workspace clients 共享 cache 时要验证 key 是否包含 workspace。
  • 离线 cache 文件可能含 prompt 和模型配置，需按敏感配置管理。
  • 发布后的强一致需求应固定 commit 或主动 invalidate，不靠等 TTL。

六、Agent Server 通用缓存不是 Prompt cache

<code>caching</code> 页面讲 LangGraph Agent Server 的 server-side KV cache：

  • <code>swr</code> beta，Agent Server 0.7.79+。
  • <code>cache_get/cache_set</code> 要求 0.7.29+。
  • 只在 Agent Server runtime 中可用，值必须 JSON serializable。
  • <code>fresh_for</code> 默认 0，<code>max_age</code> 默认且上限 1 天。

状态：

  • miss：阻塞 loader。
  • fresh：直接返回。
  • stale：返回旧值并后台刷新。
  • expired：阻塞刷新。

用它缓存 auth credential 时尤其谨慎：撤权在 fresh/max-age 窗口内可能不会立即生效。高风险权限应缩短 TTL，或接入主动失效。

七、Model Configuration

模型配置在 workspace 内共享，可供：

  • Playground。
  • Evaluators。
  • Insights。
  • Chat。
  • Fleet。
  • Prompt 保存/运行。

每个配置包含 provider、model、endpoint、调用参数、RPS 0–500、可见功能范围和认证方式。

组织管理员可以禁用 provider，组织级 deny 覆盖 workspace 的 feature access。workspace admin 不能绕过组织禁用。

八、Provider 与自定义 OpenAI-compatible endpoint

Playground 支持 OpenAI、Anthropic、Bedrock、Azure OpenAI、Google Gemini/Vertex、Groq、Mistral、DeepSeek、Fireworks、xAI 和自定义 OpenAI-compatible。

认证建议：

  • Cloud Bedrock 优先 IAM trusted entity。
  • 自托管可用 access key，但要最小权限和轮换。
  • Vertex service account JSON 是高价值长期凭据，优先短期身份/代理。
  • 自定义 endpoint 必须做 SSRF/域名、TLS、超时和 egress 控制。
  • “兼容 OpenAI”不保证 tool、stream、usage、structured output 全兼容，逐能力验证。

九、OAuth client credentials

Cloud 及自托管 0.16.0-rc.6+ 支持在每个 model configuration 保存 OAuth2 client credentials：

  • 适用于采用 OAuth2 短期访问令牌的供应商，不支持 Bedrock、Vertex、Google GenAI。
  • 支持 client_secret_basic/post、额外 body 参数和 headers。
  • secret 加密存储；编辑时不回显。
  • token broker 缓存 bearer 到过期。
  • 每个配置独立选择 OAuth 或组织 LLM auth proxy，同一 job 可混用。
  • clone 配置不会复制 secret，OAuth 会被强制关闭直到重新输入。

安全关键点：mint token 失败时会退回 workspace 的静态 provider key；没有静态 key 才得到 provider 401。这提升可用性，却可能违反“必须 OAuth”的严格认证策略。高安全环境应不给 fallback key，或明确监控 fallback。

secret 轮换要等缓存 bearer TTL 后才完全生效。

十、Prompt commit 同步 GitHub

官方示例流程：

prompt commit webhook → FastAPI 中间服务 → 拉取 Prompt/生成 manifest → GitHub API 创建或更新文件

生产实现必须补齐示例未覆盖的：

  • HMAC 验签。
  • event ID 幂等。
  • GitHub current SHA 并发冲突重试。
  • 最小权限 PAT/GitHub App。
  • secret 管理、审计、失败队列。
  • 对 public/private prompt 内容的目标仓库策略。

专用 webhook 页面要求验签与重试处理；教学 FastAPI 代码没有完整实现，不能直接上线。

十一、发布清单

  • ○ Prompt commit/tag 写入 trace。
  • ○ 模板格式和输入 schema 有测试。
  • ○ Tool 与 output schema 兼容下游。
  • ○ Prompt/model 变更有离线评估和人工抽检。
  • ○ cache TTL、失效与回滚路径明确。
  • ○ OAuth fallback 符合安全策略。
  • ○ webhook 验签、幂等、并发和重试完整。
← 继续探索AI 与智能体回到顶部 ↑