沙箱挂载 - Docs by LangChain中文

沙箱挂载会在沙箱创建时，将外部数据源附加到沙箱的文件系统。当沙箱代码需要直接访问对象存储存储桶或公共 Git 仓库中的文件，而无需将数据复制到沙箱镜像中时，可以使用挂载功能。挂载通过 Python 中的 mount_config 或 TypeScript 中的 mountConfig 进行配置。SDK 会将挂载规格发送给 LangSmith，并组合所需的身份验证代理规则以处理提供程序凭证。

沙箱挂载功能要求 Python 环境安装 langsmith[sandbox]>=0.8.16，或 TypeScript 环境安装 langsmith>=0.7.10。

在创建挂载 S3 或 GCS 的沙箱之前，请将云凭证存储为 LangSmith 工作区密钥。不要将真实的云凭证作为沙箱环境变量、命令行参数或文件传递。

配置挂载路径

每个挂载都有一个 id、一个 type 和一个 mount_path / mountPath。挂载路径必须是 /mnt/mounts 下的绝对路径。使用描述挂载源的稳定路径：

源	示例路径
S3 存储桶前缀	`/mnt/mounts/customer-data`
GCS 存储桶前缀	`/mnt/mounts/eval-datasets`
Git 仓库	`/mnt/mounts/repo`

挂载 ID 可以包含 ASCII 字母、数字、下划线和连字符。不要在同一沙箱内重复使用 ID 或挂载路径。

挂载 S3 存储桶

S3 挂载需要 AWS 身份验证。SDK 会根据 aws_auth / awsAuth 创建一个 AWS 身份验证代理规则，以便沙箱可以在不暴露真实访问密钥的情况下访问存储桶。

from langsmith.sandbox import (
    SandboxClient,
    aws_auth,
    mount_config,
    s3_mount,
    workspace_secret,
)

client = SandboxClient()

mount_cfg = mount_config(
    auth=[
        aws_auth(
            access_key_id=workspace_secret("SANDBOX_AWS_ACCESS_KEY_ID"),
            secret_access_key=workspace_secret("SANDBOX_AWS_SECRET_ACCESS_KEY"),
        )
    ],
    mounts=[
        s3_mount(
            id="customer_data",
            mount_path="/mnt/mounts/customer-data",
            bucket="example-bucket",
            prefix="datasets/customer-data",
            region="us-east-1",
            path_style=False,
            read_only=True,
        )
    ],
)

with client.sandbox(name="s3-mount-sandbox", mount_config=mount_cfg) as sb:
    result = sb.run("ls /mnt/mounts/customer-data")
    print(result.stdout)

import {
  SandboxClient,
  awsAuth,
  mountConfig,
  s3Mount,
  workspaceSecret,
} from "langsmith/sandbox";

const client = new SandboxClient();

const mountCfg = mountConfig({
  auth: [
    awsAuth({
      accessKeyId: workspaceSecret("SANDBOX_AWS_ACCESS_KEY_ID"),
      secretAccessKey: workspaceSecret("SANDBOX_AWS_SECRET_ACCESS_KEY"),
    }),
  ],
  mounts: [
    s3Mount({
      id: "customer_data",
      mountPath: "/mnt/mounts/customer-data",
      bucket: "example-bucket",
      prefix: "datasets/customer-data",
      region: "us-east-1",
      pathStyle: false,
      readOnly: true,
    }),
  ],
});

const sandbox = await client.createSandbox({
  name: "s3-mount-sandbox",
  mountConfig: mountCfg,
});

try {
  const result = await sandbox.run("ls /mnt/mounts/customer-data");
  console.log(result.stdout);
} finally {
  await sandbox.delete();
}

挂载 GCS 存储桶

GCS 挂载需要 GCP 身份验证。读写挂载需要 https://www.googleapis.com/auth/devstorage.read_write 或 https://www.googleapis.com/auth/cloud-platform OAuth 范围。只读挂载可以使用 https://www.googleapis.com/auth/devstorage.read_only。

from langsmith.sandbox import (
    SandboxClient,
    gcp_auth,
    gcs_mount,
    mount_config,
    workspace_secret,
)

client = SandboxClient()

mount_cfg = mount_config(
    auth=[
        gcp_auth(
            service_account_json=workspace_secret(
                "SANDBOX_GCP_SERVICE_ACCOUNT_JSON"
            ),
            scopes=["https://www.googleapis.com/auth/devstorage.read_write"],
        )
    ],
    mounts=[
        gcs_mount(
            id="eval_datasets",
            mount_path="/mnt/mounts/eval-datasets",
            bucket="example-bucket",
            prefix="datasets/evals",
            read_only=False,
        )
    ],
)

with client.sandbox(name="gcs-mount-sandbox", mount_config=mount_cfg) as sb:
    result = sb.run("ls /mnt/mounts/eval-datasets")
    print(result.stdout)

import {
  SandboxClient,
  gcpAuth,
  gcsMount,
  mountConfig,
  workspaceSecret,
} from "langsmith/sandbox";

const client = new SandboxClient();

const mountCfg = mountConfig({
  auth: [
    gcpAuth({
      serviceAccountJson: workspaceSecret("SANDBOX_GCP_SERVICE_ACCOUNT_JSON"),
      scopes: ["https://www.googleapis.com/auth/devstorage.read_write"],
    }),
  ],
  mounts: [
    gcsMount({
      id: "eval_datasets",
      mountPath: "/mnt/mounts/eval-datasets",
      bucket: "example-bucket",
      prefix: "datasets/evals",
      readOnly: false,
    }),
  ],
});

const sandbox = await client.createSandbox({
  name: "gcs-mount-sandbox",
  mountConfig: mountCfg,
});

try {
  const result = await sandbox.run("ls /mnt/mounts/eval-datasets");
  console.log(result.stdout);
} finally {
  await sandbox.delete();
}

挂载公共 Git 仓库

公共 Git 挂载不需要 AWS 或 GCP 身份验证。使用 HTTPS 远程 URL，并可选择固定一个分支或标签。

from langsmith.sandbox import SandboxClient, git_mount, mount_config

client = SandboxClient()

mount_cfg = mount_config(
    mounts=[
        git_mount(
            id="repo",
            mount_path="/mnt/mounts/repo",
            remote_url="https://github.com/langchain-ai/langsmith-sdk.git",
            ref={"type": "branch", "name": "main"},
            refresh_interval_seconds=60,
        )
    ],
)

with client.sandbox(name="git-mount-sandbox", mount_config=mount_cfg) as sb:
    result = sb.run("ls /mnt/mounts/repo")
    print(result.stdout)

import { SandboxClient, gitMount, mountConfig } from "langsmith/sandbox";

const client = new SandboxClient();

const mountCfg = mountConfig({
  mounts: [
    gitMount({
      id: "repo",
      mountPath: "/mnt/mounts/repo",
      remoteUrl: "https://github.com/langchain-ai/langsmith-sdk.git",
      ref: { type: "branch", name: "main" },
      refreshIntervalSeconds: 60,
    }),
  ],
});

const sandbox = await client.createSandbox({
  name: "git-mount-sandbox",
  mountConfig: mountCfg,
});

try {
  const result = await sandbox.run("ls /mnt/mounts/repo");
  console.log(result.stdout);
} finally {
  await sandbox.delete();
}

私有 Git 仓库可以在远程需要代理管理的身份验证时，使用底层的 proxy_config / proxyConfig 规则。目前还没有高级的私有 Git 身份验证辅助函数。

组合挂载

一个沙箱可以挂载多个源。构建一个包含所有挂载规格的 mount_config / mountConfig，并为这些规格使用到的每个存储桶提供程序包含其身份验证。

from langsmith.sandbox import (
    aws_auth,
    git_mount,
    gcp_auth,
    gcs_mount,
    mount_config,
    s3_mount,
    workspace_secret,
)

mount_cfg = mount_config(
    auth=[
        aws_auth(
            access_key_id=workspace_secret("SANDBOX_AWS_ACCESS_KEY_ID"),
            secret_access_key=workspace_secret("SANDBOX_AWS_SECRET_ACCESS_KEY"),
        ),
        gcp_auth(
            service_account_json=workspace_secret(
                "SANDBOX_GCP_SERVICE_ACCOUNT_JSON"
            ),
            scopes=["https://www.googleapis.com/auth/devstorage.read_write"],
        ),
    ],
    mounts=[
        s3_mount(
            id="s3_data",
            mount_path="/mnt/mounts/s3-data",
            bucket="example-s3-bucket",
        ),
        gcs_mount(
            id="gcs_data",
            mount_path="/mnt/mounts/gcs-data",
            bucket="example-gcs-bucket",
        ),
        git_mount(
            id="repo",
            mount_path="/mnt/mounts/repo",
            remote_url="https://github.com/langchain-ai/langsmith-sdk.git",
        ),
    ],
)

import {
  awsAuth,
  gitMount,
  gcpAuth,
  gcsMount,
  mountConfig,
  s3Mount,
  workspaceSecret,
} from "langsmith/sandbox";

const mountCfg = mountConfig({
  auth: [
    awsAuth({
      accessKeyId: workspaceSecret("SANDBOX_AWS_ACCESS_KEY_ID"),
      secretAccessKey: workspaceSecret("SANDBOX_AWS_SECRET_ACCESS_KEY"),
    }),
    gcpAuth({
      serviceAccountJson: workspaceSecret("SANDBOX_GCP_SERVICE_ACCOUNT_JSON"),
      scopes: ["https://www.googleapis.com/auth/devstorage.read_write"],
    }),
  ],
  mounts: [
    s3Mount({
      id: "s3_data",
      mountPath: "/mnt/mounts/s3-data",
      bucket: "example-s3-bucket",
    }),
    gcsMount({
      id: "gcs_data",
      mountPath: "/mnt/mounts/gcs-data",
      bucket: "example-gcs-bucket",
    }),
    gitMount({
      id: "repo",
      mountPath: "/mnt/mounts/repo",
      remoteUrl: "https://github.com/langchain-ai/langsmith-sdk.git",
    }),
  ],
});

缓存存储桶挂载

S3 和 GCS 挂载支持可选的缓存设置。缓存设置调整存储桶挂载使用的本地虚拟文件系统缓存；存储桶仍然是数据的真实来源。使用缓存设置来控制本地磁盘使用和回写时机，而不是将其用作单独的持久层。缓存设置不适用于 Git 挂载。

字段	描述
`max_size_bytes`	可选参数，指定本地挂载缓存的最大大小（以字节为单位）。设置正值可添加明确上限；省略则使用运行时默认值。
`writeback_seconds`	可选参数，指定缓存写入回写到存储桶前的延迟时间（以秒为单位）。默认值为 `0`。较低的值使写入更快对存储桶可见；较高的值可以减少需要重写相同文件的工作负载的写入流量。

对于只读数据集挂载，仅在需要特定的本地缓存上限时才配置 max_size_bytes。对于可写挂载，当另一个进程需要在沙箱写入后不久从 S3 或 GCS 读取对象时，请将 writeback_seconds 保持在较低值。

s3_mount(
    id="customer_data",
    mount_path="/mnt/mounts/customer-data",
    bucket="example-bucket",
    cache={
        "max_size_bytes": 2 * 1024**3,
        "writeback_seconds": 5,
    },
)

s3Mount({
  id: "customer_data",
  mountPath: "/mnt/mounts/customer-data",
  bucket: "example-bucket",
  cache: {
    max_size_bytes: 2 * 1024 ** 3,
    writeback_seconds: 5,
  },
});

相同的缓存设置可用于 GCS 挂载：

gcs_mount(
    id="eval_datasets",
    mount_path="/mnt/mounts/eval-datasets",
    bucket="example-bucket",
    cache={
        "max_size_bytes": 2 * 1024**3,
        "writeback_seconds": 5,
    },
)

gcsMount({
  id: "eval_datasets",
  mountPath: "/mnt/mounts/eval-datasets",
  bucket: "example-bucket",
  cache: {
    max_size_bytes: 2 * 1024 ** 3,
    writeback_seconds: 5,
  },
});

限制

挂载是在沙箱创建时附加的。要更改挂载，请创建一个新的沙箱。
每个沙箱在每个云提供程序的一个身份验证表面中配置其凭证。如果挂载身份验证提供了 AWS 或 GCP 凭证，请不要再为同一提供程序添加身份验证代理规则。
Git 引用可以省略，也可以设置为分支或标签。不支持提交引用。
Git 挂载不支持 read_only / readOnly 或缓存设置。

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

Edit this page on GitHub or file an issue.

​配置挂载路径

​挂载 S3 存储桶

​挂载 GCS 存储桶

​挂载公共 Git 仓库

​组合挂载

​缓存存储桶挂载

​限制

配置挂载路径

挂载 S3 存储桶

挂载 GCS 存储桶

挂载公共 Git 仓库

组合挂载

缓存存储桶挂载

限制