沙盒挂载 - 以编程方式使用文档

沙盒挂载在创建沙盒时将外部数据源附加到沙盒文件系统。当沙盒代码需要直接访问对象存储桶或公共 Git 仓库而不将数据复制到沙盒镜像中时，请使用挂载。

挂载通过以下方式配置 mount_config 在 Python 中或 mountConfig 在 TypeScript 中。SDK 将挂载规范发送到 LangSmith 并组合所需的认证代理提供程序凭证的规则。

配置挂载路径

每个挂载都有一个 id, a 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)

  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 mounts require GCP auth. Read/write mounts require the https://www.googleapis.com/auth/devstorage.read_write or 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)

  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)

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",
        ),
    ],
)

  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 挂载支持可选的缓存设置。缓存设置调整本地存储桶挂载使用的 VFS 缓存；存储桶仍是真实来源。使用缓存设置来控制本地磁盘使用和写回时间，而不是作为独立的持久层。缓存设置不适用于 Git 挂载。

字段	描述
`max_size_bytes`	本地挂载缓存的可选最大大小（以字节为单位）。设置正值以添加显式上限；省略以保留运行时默认值。
`writeback_seconds`	缓存写入写回存储桶之前的可选延迟（以秒为单位）。默认值为 `0`。较低的值使写入更快对 bucket 可见；较高的值可以减少重写相同文件的工作负载的写入流量。

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

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 或缓存设置。