LangSmith SDK 配置文件让您可以保存 API 密钥、端点和工作区 ID 在可重用的 JSON 文件中，而不是在每个 shell 会话中设置相同的环境变量。

在以下情况下使用配置文件 LangSmith Cloud 区域、自托管实例或 工作区 （频繁切换），或者当您希望远程运行时从挂载的文件加载相同的 SDK 配置时。

最低版本

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

配置文件位置

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

~/.langsmith/config.json

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

TypeScript SDK 仅在 Node.js 类似的运行时中加载配置文件。浏览器和 Web Worker 运行时无法访问文件系统，因此请在这些环境中显式传递配置。

创建配置文件

创建 ~/.langsmith/config.json ，包含 profiles 对象。每个配置文件可以定义：

{
  "current_profile": "dev",
  "profiles": {
    "dev": {
      "api_url": "https://api.smith.langchain.com",
      "api_key": "",
      "workspace_id": ""
    },
    "eu": {
      "api_url": "https://eu.api.smith.langchain.com",
      "api_key": "",
      "workspace_id": ""
    },
    "apac": {
      "api_url": "https://apac.api.smith.langchain.com",
      "api_key": "",
      "workspace_id": ""
    }
  }
}

限制文件权限，使只有您的用户可以读取它：

chmod 600 ~/.langsmith/config.json

选择配置文件

SDK 按以下顺序选择配置文件：

1. LANGSMITH_PROFILE（如果已设置）。
2. current_profile （如果在配置文件中已设置）。
3. 名为 default的配置文件（如果存在）。

例如：

LangSmith CLI 还接受一个全局 --profile 标志，该标志优先于 LANGSMITH_PROFILE 用于该命令：

langsmith --profile eu project list

使用 CLI 管理配置文件

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

要从现有 API 密钥创建 API 密钥配置文件：

langsmith profile create dev \
  --workspace-id  \
  --set-current

您也可以将密钥和端点作为标志传递。在共享计算机上优先使用环境变量，因为 shell 历史记录可能会记录命令标志。

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

常用配置文件命令：

使用 --format pretty 获取人类可读的表格：

langsmith --format pretty profile list

使用以下方式进行身份验证 langsmith auth login

运行 langsmith auth login 使用 OAuth 而非手动创建 API 密钥配置文件进行身份验证。该命令启动基于浏览器的设备授权流程，将 OAuth 令牌存储在所选配置文件中，并将其设置为当前配置文件。

langsmith auth login

使用以下方式选择配置文件 --profile or LANGSMITH_PROFILE:

langsmith auth login --profile dev

对于无头环境，阻止自动打开浏览器并传递工作区 ID：

langsmith auth login \
  --profile prod \
  --no-browser \
  --workspace-id 

langsmith auth login 按以下顺序选择配置文件名称：

1. --profile（如果已传递）。
2. LANGSMITH_PROFILE（如果已设置）。
3. current_profile 配置文件中（如果已设置）。
4. default.

它按以下顺序选择 API URL：

1. --api-url（如果已传递）。
2. LANGSMITH_ENDPOINT（如果已设置）。
3. 所选配置文件的 api_url（如果存在）。
4. 默认 LangSmith Cloud 端点。

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

覆盖配置文件值

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

旧的 LANGCHAIN_API_KEY, LANGCHAIN_ENDPOINT和 LANGCHAIN_WORKSPACE_ID 别名仍然可用，但新配置建议使用 LANGSMITH_* 名称。

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

在代码中使用配置文件

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

from langsmith import Client

client = Client()

const client = new Client();

若要在代码中覆盖配置文件，请显式传递值：

from langsmith import Client

client = Client(api_key="")

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

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

对于远程运行时，将配置文件作为密钥文件挂载并设置 LANGSMITH_CONFIG_FILE 为该路径，并设置

Docker

将本地配置文件目录挂载到容器中：

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 刷新令牌时才使用读写挂载：

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 密钥：

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

挂载密钥并让 SDK 指向它：

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 密钥卷是只读的。对于此模式，请使用 API 密钥配置文件，或者如果您的 OAuth 配置文件必须刷新并持久化令牌，请使用可写的密钥同步机制。

远程开发和 CI

在远程开发环境或 CI 作业中，将配置文件 JSON 存储在平台的密钥存储中，在运行时将其写入临时文件，并设置 LANGSMITH_CONFIG_FILE 为该文件路径。

mkdir -p "$RUNNER_TEMP/langsmith"
printf '%s' "$LANGSMITH_PROFILE_JSON" > "$RUNNER_TEMP/langsmith/config.json"
chmod 600 "$RUNNER_TEMP/langsmith/config.json"

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