配置文件

用一个本地配置文件来配置 LangSmith SDK 凭据和端点。

LangSmith SDK 配置文件让你能够把 API 密钥、端点和工作区 ID 保存在一个可复用的 JSON 文件中，而不必在每个 shell 会话里都设置同样的环境变量。

当你经常在LangSmith Cloud 区域、自托管实例或工作区之间切换时，或当你想让一个远程运行时从一个挂载的文件加载同样的 SDK 配置时，使用配置文件。

WARNING

配置文件可能包含 API 密钥和 OAuth 刷新令牌。不要把配置提交到版本控制、烘焙进容器镜像或打印到日志中。像对待其他凭据一样小心地存储和挂载它们。

最低版本

配置文件支持在以下发布版本中可用：

工具或 SDK	最低版本
LangSmith CLI profile 命令	`v0.2.26`
`langsmith auth login`	`v0.2.30`
Go SDK	`v0.7.0`
Python SDK	`v0.8.1`
TypeScript SDK	`v0.6.1`
Java SDK	`v0.1.0-beta.3`

配置文件位置

默认情况下，SDK在以下位置寻找配置文件：

text

~/.langsmith/config.json

要使用不同的路径，设置 LANGSMITH_CONFIG_FILE：

shell

export LANGSMITH_CONFIG_FILE=/path/to/langsmith-config.json

TypeScript SDK 只在类 Node.js 的运行时中加载配置文件。浏览器和 web worker 运行时没有文件系统访问，因此在那些环境中显式传入配置。

创建一个配置文件

创建一个带 profiles 对象的 ~/.langsmith/config.json。每个配置文件可定义：

字段	描述
`api_url`	LangSmith API 端点。使用与你为 `LANGSMITH_ENDPOINT` 所设相同的值。
`api_key`	LangSmith API 密钥。参阅创建账户和 API 密钥。
`workspace_id`	工作区 ID。当 API 密钥能访问多个工作区时必需。
`oauth`	由 LangSmith 工具创建的 OAuth 令牌元数据。

json

{
  "current_profile": "dev",
  "profiles": {
    "dev": {
      "api_url": "https://api.smith.langchain.com",
      "api_key": "<LANGSMITH_API_KEY>",
      "workspace_id": "<WORKSPACE_ID>"
    },
    "eu": {
      "api_url": "https://eu.api.smith.langchain.com",
      "api_key": "<EU_LANGSMITH_API_KEY>",
      "workspace_id": "<EU_WORKSPACE_ID>"
    },
    "apac": {
      "api_url": "https://apac.api.smith.langchain.com",
      "api_key": "<APAC_LANGSMITH_API_KEY>",
      "workspace_id": "<APAC_WORKSPACE_ID>"
    }
  }
}

限制该文件，使只有你的用户能读取它：

shell

chmod 600 ~/.langsmith/config.json

选择一个配置文件

SDK 按此顺序选择配置文件：

LANGSMITH_PROFILE，如果设置了。
配置文件中的 current_profile，如果设置了。
一个名为 default 的配置文件，如果存在。

例如：

shell

export LANGSMITH_PROFILE=eu

LangSmith CLI 还接受一个全局 --profile 标志，它对那条命令优先于 LANGSMITH_PROFILE：

shell

langsmith --profile eu project list

用 CLI 管理配置文件

使用 LangSmith CLI 来创建、检查、切换和删除配置文件，而无需手动编辑 JSON 文件。

要从一个现有的 API 密钥创建一个 API-key 配置文件：

shell

export LANGSMITH_API_KEY=<LANGSMITH_API_KEY>
langsmith profile create dev \
  --workspace-id <WORKSPACE_ID> \
  --set-current

你也可以把密钥和端点作为标志传入。在共享机器上更倾向于用环境变量，因为 shell 历史可能记录命令标志。

shell

langsmith profile create eu \
  --api-key <EU_LANGSMITH_API_KEY> \
  --api-url https://eu.api.smith.langchain.com \
  --workspace-id <EU_WORKSPACE_ID>

常见的配置文件命令：

命令	描述
`langsmith profile list`	列出已保存的配置文件。别名：`langsmith profile ls`。
`langsmith profile show <name>`	显示一个已保存的配置文件。秘密值在输出中会被隐藏。
`langsmith profile use <name>`	设置配置文件中的 `current_profile`。
`langsmith profile set-workspace <workspace-id>`	为所选配置文件设置默认工作区。
`langsmith profile delete <name>`	删除一个已保存的配置文件。

输出默认为人类可读的表格。用 --format json 获得可脚本化的输出：

shell

langsmith --format json profile list

用 `langsmith auth login` 进行身份验证

运行 langsmith auth login 以用 OAuth 进行身份验证，而非手动创建一个 API-key 配置文件。该命令启动一个基于浏览器的设备授权流程，把 OAuth 令牌存入所选的配置文件，并把那个配置文件设为当前。

NOTE

langsmith auth login 从 LangSmith CLI v0.2.46 起也能针对自托管实例工作，前提是部署在 LangSmith 0.16 或更高版本并已启用 OAuth 授权服务器。当在你的 Helm chart 中设置了 config.hostname并且配置了一个签名 JWKS（config.signingJwks 或 config.existingSecretName 中的 langsmith_signing_jwks 键）时，OAuth 授权服务器会被自动启用。在更早的部署上，或如果没有配置签名 JWKS，请改为创建一个 API-key 配置文件。

shell

langsmith auth login

用 --profile 或 LANGSMITH_PROFILE 选择配置文件：

shell

langsmith auth login --profile dev

对于一个自托管实例，传入它的基础 URL。CLI 会读取该部署的授权服务器元数据以找到 OAuth 端点：

shell

langsmith auth login --api-url https://langsmith.example.com --profile self-hosted

自托管 OAuth 登录需要 Helm chart 0.16.0 或更高并带一个签名 JWKS。有关配置，参阅启用远程 MCP。否则创建一个 API-key 配置文件。

对于一个无头环境，抑制自动打开浏览器并传入一个工作区 ID：

shell

langsmith auth login \
  --profile prod \
  --no-browser \
  --workspace-id <WORKSPACE_ID>

langsmith auth login 按此顺序选择配置文件名：

--profile，如果传入。
LANGSMITH_PROFILE，如果设置了。
配置文件中的 current_profile，如果设置了。
default。

它按此顺序选择 API URL：

--api-url，如果传入。
LANGSMITH_ENDPOINT，如果设置了。
所选配置文件的 api_url，如果存在。
默认的 LangSmith Cloud 端点。

登录之后，CLI 和 SDK 可以使用已保存的配置文件。CLI 会在需要时刷新 OAuth 令牌，并把刷新后的令牌字段写回配置文件。当环境或构造器 API-key 身份验证未设置时，SDK 也会使用配置文件中的 OAuth 访问令牌。

覆盖配置文件值

显式的客户端构造器参数和环境变量优先于配置文件值。

设置	优先级
端点	构造器 `api_url` 或 `apiUrl`，然后 `LANGSMITH_ENDPOINT`，然后配置文件 `api_url`，然后默认的 LangSmith Cloud 端点。
身份验证	构造器 API 密钥，然后 `LANGSMITH_API_KEY`，然后配置文件 OAuth 访问令牌，然后配置文件 `api_key`。
工作区	构造器 `workspace_id` 或 `workspaceId`，然后 `LANGSMITH_WORKSPACE_ID`，然后配置文件 `workspace_id`。

较旧的 LANGCHAIN_API_KEY、LANGCHAIN_ENDPOINT 和 LANGCHAIN_WORKSPACE_ID 别名仍然有效，但对于新配置请优先使用 LANGSMITH_* 名称。

如果一个配置文件同时包含 oauth.access_token 和 api_key，SDK 首先使用 OAuth 访问令牌。如果存在一个 OAuth 刷新令牌且访问令牌已过期或即将过期，SDK 可以刷新令牌并把更新后的令牌字段写回配置文件。

NOTE

如果你把一个配置文件作为只读挂载，OAuth 令牌刷新无法持久化更新后的令牌。只读挂载适用于 API-key 配置文件。只有当你有意依赖 OAuth 令牌刷新时才使用可写挂载。

在代码中使用配置文件

当配置文件存在时，正常创建客户端：

PythonTypeScript

python

from langsmith import Client

client = Client()

typescript

import { Client } from "langsmith";

const client = new Client();

要在代码中覆盖一个配置文件，显式传入该值：

PythonTypeScript

python

from langsmith import Client

client = Client(api_key="<LANGSMITH_API_KEY>")

typescript

import { Client } from "langsmith";

const client = new Client({ apiKey: "<LANGSMITH_API_KEY>" });

在远程运行时中挂载配置文件

对于远程运行时，把配置文件作为一个机密文件挂载，并把 LANGSMITH_CONFIG_FILE 设为挂载的路径。不要把该文件复制到镜像或仓库中。

Docker

把你本地的配置文件目录挂载进容器：

shell

docker run --rm \
  -e LANGSMITH_CONFIG_FILE=/home/app/.langsmith/config.json \
  -e LANGSMITH_PROFILE=prod \
  -v "$HOME/.langsmith:/home/app/.langsmith:ro" \
  my-image

只有当配置文件使用 OAuth 刷新令牌时才使用可读写挂载：

shell

docker run --rm \
  -e LANGSMITH_CONFIG_FILE=/home/app/.langsmith/config.json \
  -e LANGSMITH_PROFILE=prod \
  -v "$HOME/.langsmith:/home/app/.langsmith" \
  my-image

Kubernetes

从配置文件创建一个 Kubernetes secret：

shell

kubectl create secret generic langsmith-profile \
  --from-file=config.json="$HOME/.langsmith/config.json"

挂载该 secret 并让 SDK 指向它：

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
spec:
  template:
    spec:
      containers:
        - name: app
          image: my-image
          env:
            - name: LANGSMITH_CONFIG_FILE
              value: /var/run/langsmith/config.json
            - name: LANGSMITH_PROFILE
              value: prod
          volumeMounts:
            - name: langsmith-profile
              mountPath: /var/run/langsmith
              readOnly: true
      volumes:
        - name: langsmith-profile
          secret:
            secretName: langsmith-profile

Kubernetes secret 卷是只读的。对此模式使用 API-key 配置文件，或者如果你的 OAuth 配置文件必须刷新并持久化令牌，则使用一个可写的机密同步机制。

远程开发与 CI

在远程开发环境或 CI 作业中，把配置 JSON 存储到平台的机密存储中，在运行时写到一个临时文件，并把 LANGSMITH_CONFIG_FILE 设为那个文件路径。

shell

mkdir -p "$RUNNER_TEMP/langsmith"
printf '%s' "$LANGSMITH_PROFILE_JSON" > "$RUNNER_TEMP/langsmith/config.json"
chmod 600 "$RUNNER_TEMP/langsmith/config.json"
export LANGSMITH_CONFIG_FILE="$RUNNER_TEMP/langsmith/config.json"
export LANGSMITH_PROFILE=prod

对于托管的 LangSmith Cloud，把这些值配置为环境变量或工作区机密，除非该平台明确支持挂载机密文件。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织