配置文件配置 - Docs by LangChain中文

LangSmith SDK 配置文件允许您将 API 密钥、端点和工作区 ID 保存在一个可重用的 JSON 文件中，而不是在每个 shell 会话中设置相同的环境变量。当您经常在 LangSmith 云区域、自托管实例或工作区之间切换时，或者当您希望远程运行时从一个挂载的文件加载相同的 SDK 配置时，请使用配置文件。

配置文件可能包含 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 会在以下位置查找配置文件：

~/.langsmith/config.json

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

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

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

创建配置文件

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

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

{
  "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>"
    }
  }
}

限制文件权限，仅允许您的用户读取：

chmod 600 ~/.langsmith/config.json

选择配置文件

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

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

例如：

export LANGSMITH_PROFILE=eu

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

langsmith --profile eu project list

使用 CLI 管理配置文件

使用 LangSmith CLI 来创建、检查、切换和删除配置文件，无需手动编辑 JSON 文件。要从现有 API 密钥创建 API 密钥配置文件：

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

您也可以通过标志传递密钥和端点。在共享机器上，建议使用环境变量，因为 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 pretty 获取人类可读的表格：

langsmith --format pretty profile list

运行 langsmith auth login 通过 OAuth 进行认证，而不是手动创建 API 密钥配置文件。该命令会启动一个基于浏览器的设备授权流程，将 OAuth 令牌存储在所选的配置文件中，并将该配置文件设置为当前配置。

langsmith auth login 目前仅支持 LangSmith Cloud (SaaS)。对于自托管或其他非 SaaS 的 LangSmith 端点，请改为创建 API 密钥配置文件。

langsmith auth login

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

langsmith auth login --profile dev

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

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 密钥认证未设置时，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 可以刷新令牌并将更新后的令牌字段写回配置文件。

如果您将配置文件挂载为只读，则 OAuth 令牌刷新无法持久化更新的令牌。只读挂载适用于 API 密钥配置文件。仅当您明确依赖 OAuth 令牌刷新时，才使用可写挂载。

在代码中使用配置文件

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

from langsmith import Client

client = Client()

import { Client } from "langsmith";

const client = new Client();

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

from langsmith import Client

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

import { Client } from "langsmith";

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

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

对于远程运行时，请将配置文件作为密钥文件挂载，并将 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"
export LANGSMITH_CONFIG_FILE="$RUNNER_TEMP/langsmith/config.json"
export LANGSMITH_PROFILE=prod

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

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​最低版本

​配置文件位置

​创建配置文件

​选择配置文件

​使用 CLI 管理配置文件

​使用 langsmith auth login 进行认证

​覆盖配置文件值

​在代码中使用配置文件

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

​Docker

​Kubernetes

​远程开发和 CI

最低版本

配置文件位置

创建配置文件

选择配置文件

使用 CLI 管理配置文件

使用 `langsmith auth login` 进行认证

覆盖配置文件值

在代码中使用配置文件

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

Docker

Kubernetes

远程开发和 CI