---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - langchain
  - langsmith
  - prompt-engineering
  - model-configuration
topic: LangSmith Prompt 工程、版本治理与模型配置
sources:
  - https://docs.langchain.com/langsmith/caching
  - https://docs.langchain.com/langsmith/create-a-prompt
  - https://docs.langchain.com/langsmith/custom-openai-compliant-model
  - https://docs.langchain.com/langsmith/manage-prompts
  - https://docs.langchain.com/langsmith/manage-prompts-programmatically
  - https://docs.langchain.com/langsmith/managing-model-configurations
  - https://docs.langchain.com/langsmith/model-configurations
  - https://docs.langchain.com/langsmith/playground-model-providers
  - https://docs.langchain.com/langsmith/prompt-commit
  - https://docs.langchain.com/langsmith/prompt-engineering-concepts
  - https://docs.langchain.com/langsmith/prompt-engineering-quickstart
  - https://docs.langchain.com/langsmith/prompt-template-format
  - https://docs.langchain.com/langsmith/write-prompt-with-ai
last_verified: 2026-08-11
---

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

> [!summary]
> 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 验签、幂等、并发和重试完整。