BytesRouter

主题

LangSmith 文档版本 跟随上游 源快照 94678a41 更新于 2026-10-18

管理模型配置

管理模型配置并控制它们在各 LangSmith 功能中的可用性。

模型配置定义了 LangSmith 功能在调用一家 AI 提供商时使用的模型和参数。一个共享的配置库横跨你的整个工作区，因此你创建的任何配置都能在以下功能间使用而无需重复：

工作区管理员可以创建、编辑和删除配置，并控制每个功能可用的提供商和模型。非管理员成员可以查看配置但不能修改它们。

配置也可以携带 OAuth 客户端凭据，因此 LangSmith 在请求时向你的 IdP 铸造短生命周期的 bearer 令牌，而非使用一个静态 API 密钥。

功能访问

Feature Access 表为每个 LangSmith 功能独立控制提供商和模型的可用性。

功能模型选择体验
Playground完整的模型控制——查看并调整所有参数。无内置模型；依赖工作区配置。
Evaluators完整的模型控制——查看并调整所有参数。无内置模型；依赖工作区配置。
Fleet默认从一个精选列表选择。你也可以添加自定义工作区配置。
Chat默认从一个精选列表选择。你也可以添加自定义工作区配置。
Insights（Thinking）用于深度分析的模型。默认从一个带提供商推荐的精选列表选择。你也可以添加自定义工作区配置。
Insights（Summarization）用于轻量摘要的模型。默认从一个带提供商推荐的精选列表选择。你也可以添加自定义工作区配置。

所有功能都支持自定义工作区配置，因此你可以使用任何提供商或模型——即使对那些默认展示精选列表的功能也是如此。

NOTE

Insights 使用两个独立的行——一行用于分析，一行用于摘要。如果你为任一行选了不兼容的提供商或非推荐模型，UI 会显示一个警告。

配置功能访问

要在 UI 中配置功能访问：

  1. 导航到 Settings > Model configurations。
  2. 在 Feature Access 表中，找到你想配置的功能。
  3. 点击 Enabled Providers 并为那个功能开启或关闭提供商。
  4. 点击 Available Models 并选择用户可以从哪些模型中选。
  5. 用 Default Model 下拉菜单设一个用户打开该功能时预选的模型。

NOTE

在 Settings > Model providers 中为整个组织禁用的提供商，在本表中会显示为锁定且无法按工作区重新启用。见组织级提供商控制。

组织级提供商控制

提供商可用性在两个层级控制：

  • 组织（组织管理员）：为整个组织——每个工作区和每个功能——开启或关闭一个提供商。在 Settings > Model providers 中管理。
  • 工作区（工作区管理员）：上面的 Feature Access 表，在单个工作区内按功能控制提供商和模型的可用性。

组织级优先。为组织禁用的一个提供商在每个工作区和每个功能中都不可用，并在每个工作区的 Feature Access 表中显示为锁定——工作区管理员能看到它但无法重新启用。工作区只能在组织允许的提供商中选择。

管理组织级提供商需要 Organization Admin 角色（organization:manage 权限），且面向组织（而非个人账户）在 LangSmith Cloud 和 Self-hosted 上可用。

为一个组织禁用一个提供商

  1. 导航到 Settings 下的 Model providers 页面。
  2. 把一个提供商切换为关以在整个组织禁用它，或切换为开以重新启用它。

组织作用域的模型配置

NOTE

组织作用域的模型配置仅在 LangSmith Self-hosted 和 Cloud Enterprise 上可用。

组织管理员可以在组织层创建模型配置，因此一个单一配置就能在组织中跨每个工作区使用，而无需按工作区重复。

组织作用域的配置会与各工作区的 Settings > Model configurations 页上 Configurations 表中的工作区作用域配置并列展示。要让一个 org 作用域的配置在 Fleet、Playground、Evaluators 或其他功能中可用，工作区管理员必须在该工作区的 Feature Access 表中启用它。

创建一个组织作用域的配置

创建一个组织作用域的配置需要 Organization Admin 角色：

  1. 导航到组织层的 Settings > Model configurations。
  2. 在 Configurations 下，点击 + Create。
  3. 选择一个 Provider 和 Model，并完成其余字段。
  4. 点击 Save。

在一个工作区中启用一个 org 作用域的配置

当一个 org 作用域的配置被创建后，工作区管理员必须先启用它，它才会出现在工作区功能中：

  1. 在工作区中，导航到 Settings > Model configurations。
  2. 在 Configurations 表中找到那个 org 作用域的配置。
  3. 在 Feature Access 表中，为它应当出现的每个功能启用该配置。

限制

在处理 org 作用域的配置时，请记住以下约束：

  • 作用域不可变。 一个保存为 org 作用域的配置不能改为工作区作用域，一个工作区作用域的配置也不能提升为 org 作用域。若需要更改作用域，请新建一个配置。
  • 名称冲突时工作区优先。 当一个工作区配置和一个 org 作用域配置共享同名时，工作区版本优先。
  • 机密存储位置。 在 LangChain Cloud（非 BYOC）上，org 作用域配置的机密存在 LangChain Cloud 控制平面上。在 BYOC 部署中，你可以用数据平面切换器配置模型机密写入的位置。

配置

Configurations 表是你工作区一个命名模型配置的共享库。你在 LangSmith 中创建的（包括从 Playground）配置会出现在这里，你可以跨所有功能复用它们。

创建一个配置

  1. 导航到 Settings > Model configurations。

  2. 在 Configurations 下，点击 + Create。

  3. 选择一个 Provider 和 Model。

  4. 输入 API Key Name——你工作区中存提供商 API 密钥的那个机密的名字。

  5. 按需调整参数。参数被分为以下部分的组：

    • 标准采样设置：temperature、top P、top K、presence penalty、frequency penalty、max output tokens
    • Reasoning：reasoning effort、service tier
    • Provider config：provider API、base URL
    • Options：stop sequences、seed、JSON mode、extra headers、每秒请求数、extra parameters

    可用参数因提供商而异——详情参阅你提供商的文档。

  6. 点击 Save。

编辑一个配置

  1. 在 Configurations 表中，点击该配置旁边的溢出菜单

。 2. 选择 Edit。 3. 更新配置并点击 Save。

删除一个配置

  1. 在 Configurations 表中，点击该配置旁边的溢出菜单

。 2. 选择

Delete 并确认。

OAuth 客户端凭据

NOTE

OAuth 客户端凭据在运行 0.16.0-rc.6 或更高版本的 LangSmith Cloud 和 Self-hosted 部署上可用。

当一个模型配置位于一个 OAuth2 网关之后时，你可以把 OAuth client_credentials 直接存在该配置上，而非分发一个静态 API 密钥。LangSmith 在请求时把这些凭据交换为一个短生命周期的 bearer 令牌，在出站 LLM 调用上以 Authorization: Bearer <token> 附上它，并在令牌过期前刷新它。这是一个按配置、自助的替代方案，区别于把工作区路由通过 LLM 身份验证代理；两者按配置互斥。

OAuth 客户端凭据在所有支持自定义模型配置的方案上都可用。Use Custom OAuth 切换适用于 bearer 令牌提供商（OpenAI、Anthropic、OpenAI 兼容端点及类似），不支持 Bedrock、Gemini Enterprise Agent Platform 或 Google GenAI，它们用原生云身份验证。该切换对 LangServe (Deprecated) 预设也隐藏。

在模型配置上配置 OAuth

配置 OAuth 需要 Workspace Admin 角色，或一个带 workspaces:manage-model-configs 权限的自定义角色。没有它的成员会看到 OAuth 字段被禁用，带一个隐藏的机密提示。在 LangSmith UI 中：

  1. 导航到 Settings > Model configurations，要么点击 + Create，要么通过溢出菜单打开一个现有行

Edit。

  1. 选择一个兼容的提供商并照常配置模型参数。
  2. 把 Use Custom OAuth 切换为开。
  3. 填写 OAuth 字段：
    • Token URL：IdP 令牌端点，例如 https://login.example.com/oauth/token。
    • Client ID：OAuth 客户端标识符。
    • Client Secret：OAuth 客户端机密。静态加密存储。
    • Token Endpoint Auth Method：client_secret_basic 或 client_secret_post。
    • Extra parameters：在令牌请求体中发送的键/值行。用这些行放 scope、audience、resource 或 IdP 期望的任何其他参数。发送多个 scope 时每值加一行；重复的键作为多值对发送。
    • Extra headers：随令牌请求发送的额外标头。像 Authorization 这样的保留标头在保存时会被拒绝。
  4. 点击 Save。
Model configuration Create modal in LangSmith Settings with Use Custom OAuth toggled on, showing Token URL, Client ID, masked Client Secret, and Token Endpoint Auth Method set to HTTP Basic.Model configuration Create modal in LangSmith Settings with Use Custom OAuth toggled on, showing Token URL, Client ID, masked Client Secret, and Token Endpoint Auth Method set to HTTP Basic.

编辑语义

OAuth 字段遵循保护所存机密的编辑行为：

  • 机密往返：服务器把机密返回为 ********。输入渲染为空，带一个*"Secret is set. Type to replace."*提示。不重新输入就提交会保持所存机密不变。
  • 切换关保留凭据：把 Use Custom OAuth 切换为关会停用 OAuth 流程但保留所存字段。再切回开会用同样的凭据继续使用。
  • 清空一个字段：编辑配置并把该字段置空以显式清除它。
  • 通过另存为预设克隆：当你把一个一次性配置存为一个新预设时，非机密的 OAuth 字段会复制到新行。机密因从不被读取暴露而无法转移，因此在重新输入机密前 OAuth 会在克隆上被强制禁用。

请求如何流转

当一个请求针对一个启用 OAuth 的配置运行时，LangSmith 通过一个内部代理铸造一个 bearer，缓存结果，并在缓存的令牌过期前把 bearer 印在每个出站 LLM 调用上。

sequenceDiagram
    autonumber
    participant Caller as LangSmith service<br/>(Playground, Evals, Insights, Chat, Fleet)
    participant Broker as Token broker
    participant Cache as Redis cache
    participant IdP as Customer IdP
    participant LLM as Upstream LLM provider

    Caller->>Broker: Mint token for configuration X
    Broker->>Cache: Lookup cached token for X
    alt Cache hit
        Cache-->>Broker: Cached token
    else Cache miss or expired
        Broker->>IdP: client_credentials grant
        IdP-->>Broker: access_token + expires_in
        Broker->>Cache: Store until expiry
    end
    Broker-->>Caller: access_token
    Caller->>LLM: Request with Authorization: Bearer <token>
    LLM-->>Caller: Response

在 OAuth 和 LLM 身份验证代理之间的路由是按配置、而非按组织。每个请求根据配置的 OAuth 状态解析为 OAuth 或 LLM 身份验证代理。单个多模型作业（例如带独立 Thinking 和 Summarization 模型的 Insights）可以混合两种流程，因为每个模型独立解析。

回退行为

如果代理无法铸造令牌（IdP 不可达、凭据无效、配置在请求准备与执行之间被删除），请求会回退到该提供商的静态工作区 API 密钥。若未设工作区密钥，预期出站调用会得到提供商 401。

令牌轮换只在缓存的 bearer 过期后才传播。围绕 IdP 配置的访问令牌 TTL 来规划轮换。

界面覆盖

启用 OAuth 的配置在任何模型配置被消费之处都受尊重：

  • Playground：聊天运行和实验运行。
  • Evaluators：当每个提示都解析为一个启用 OAuth 的配置时，LLM-as-judge 配置、Reuse、Preview Test 和 Evaluator Details Test 都跳过工作区机密提示。
  • Insights：Thinking 和 Summarization 配置独立解析。
  • Chat
  • Fleet

当一个配置上启用了 OAuth 时，LangSmith 不会为该配置提示一个工作区机密，因为代理在请求时提供凭据。

安全与审计

  • 静态加密：客户端机密用与工作区机密相同派生方式的 Fernet 加密。
  • Bearer 缓存：访问令牌被缓存直到过期，且从不写入日志。

常见问题

一整套 OAuth 凭据能跨工作区共享吗？

不能。OAuth 凭据存在模型配置上，而配置是工作区作用域的。每个工作区输入它自己的凭据，即使凭据指向同一个 IdP 客户端。

为什么我启用 OAuth 的配置突然在用静态工作区密钥？

如果代理无法铸造 bearer（IdP 不可达、凭据无效、配置在请求准备与执行之间被删除），请求会回退到该提供商的静态工作区 API 密钥。重新打开模型配置并验证 Token URL 可达、Client ID 和机密是最新的，且 Token Endpoint Auth Method 与你 IdP 期望的一致。

我如何轮换客户端机密？

编辑模型配置并在 Client Secret 字段重新输入机密。旧机密在保存时被覆盖。Redis 缓存的 bearer 会继续工作直到其 TTL 过期，之后代理用轮换后的机密铸造一个新 bearer。

OAuth 和 LLM 身份验证代理能一起用吗？

能。路由按配置。启用 OAuth 的配置用 OAuth；没有它的配置在代理于组织层启用时，落到 LLM 身份验证代理。单个多模型作业可以混合两种流程。

友情链接

  • Agents.md面向 AI 编码助手的仓库说明文件规范
  • LangChainLangChain 是一个开放的Agent平台
  • LangSmithAgent 工程平台：可观测与评估、部署、Fleet、Engine 等
  • EmbabelEmbabel 是一个JVM平台Agent框架
  • SpringAISpringAI 是一个基于 Spring 的 AI 框架
  • MCPModel Context Protocol，连接 AI 应用与外部数据/工具的开放标准
  • LangChain4jJava 生态的 LLM 应用开发框架
  • LlamaIndex把数据接入 LLM 的框架与文档平台
  • LlamaParse智能体式 OCR 文档解析：把 PDF、扫描件变成 LLM 可用的文本与结构化数据
  • LiteParse本地优先、轻量的文档解析库，不需要 API key
  • CrewAI多智能体编排框架：以 Crew/Flow 组织自主协作的 AI Agent
  • MAFMicrosoft Agent Framework，企业级 .NET/Python 智能体框架

BytesRouter 是社区翻译站点，所有译文仅供参考，一切以官方英文原文为准。

© 2026 BytesRouter · 译文采用 CC BY 4.0 许可