` | - | 环境变量 |
| `blockNetwork` | `boolean` | - | 阻止网络访问 |
| `name` | `string` | - | 沙箱名称（在应用内唯一） |
## GPU 支持
Modal 支持用于 ML 工作负载的 NVIDIA GPU：
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const sandbox = await ModalSandbox.create({
imageName: "python:3.12-slim",
gpu: "T4", // 或 "L4"、"A10G"、"A100"、"H100"
});
```
## 卷和密钥
挂载 Modal 卷以实现持久化存储，并将密钥作为环境变量注入：
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// 卷和密钥必须首先在 Modal 中创建
const sandbox = await ModalSandbox.create({
imageName: "python:3.12-slim",
volumes: {
"/data": "my-data-volume",
"/models": "my-models-volume",
},
secrets: ["my-api-keys", "database-credentials"],
});
// /data 和 /models 中的文件在沙箱重启后仍然存在
await sandbox.execute("echo 'Hello' > /data/test.txt");
// 密钥可作为环境变量使用
await sandbox.execute("echo $API_KEY");
```
## 初始文件
在创建时预填充沙箱文件：
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const sandbox = await ModalSandbox.create({
imageName: "python:3.12-slim",
initialFiles: {
"/app/main.py": 'print("Hello from Python!")',
"/app/config.json": JSON.stringify({ name: "my-app" }, null, 2),
},
});
const result = await sandbox.execute("python /app/main.py");
```
## 访问 Modal SDK
对于 `BaseSandbox` 未暴露的高级功能，访问底层的 Modal SDK：
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
const modalSandbox = await ModalSandbox.create();
const client = modalSandbox.client; // ModalClient
const instance = modalSandbox.instance; // Sandbox
// 直接 SDK 操作
const process = await instance.exec(["python", "-c", "print('Hello')"], {
stdout: "pipe",
stderr: "pipe",
});
```
## 重新连接到现有沙箱
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
// 通过 ID 重新连接
const reconnected = await ModalSandbox.fromId(sandboxId);
// 通过名称重新连接
const reconnected2 = await ModalSandbox.fromName("my-app", "my-sandbox");
```
## 工厂函数
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { createModalSandboxFactory, createModalSandboxFactoryFromSandbox } from "@langchain/modal";
// 每次调用创建新沙箱
const factory = createModalSandboxFactory({ imageName: "python:3.12-slim" });
// 或者跨调用重用现有沙箱
const sandbox = await ModalSandbox.create();
const reuseFactory = createModalSandboxFactoryFromSandbox(sandbox);
```
## 错误处理
```typescript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import { ModalSandboxError } from "@langchain/modal";
try {
await sandbox.execute("some command");
} catch (error) {
if (error instanceof ModalSandboxError) {
switch (error.code) {
case "NOT_INITIALIZED":
await sandbox.initialize();
break;
case "COMMAND_TIMEOUT":
console.error("Command took too long");
break;
case "AUTHENTICATION_FAILED":
console.error("Check your Modal token credentials");
break;
}
}
}
```
### 错误代码
| 代码 | 描述 |
| ------------------------- | -------------------------- |
| `NOT_INITIALIZED` | 沙箱未初始化 - 调用 `initialize()` |
| `ALREADY_INITIALIZED` | 不能初始化两次 |
| `AUTHENTICATION_FAILED` | Modal 令牌无效或缺失 |
| `SANDBOX_CREATION_FAILED` | 创建沙箱失败 |
| `SANDBOX_NOT_FOUND` | 沙箱 ID/名称未找到或已过期 |
| `COMMAND_TIMEOUT` | 命令执行超时 |
| `COMMAND_FAILED` | 命令执行失败 |
| `FILE_OPERATION_FAILED` | 文件读写失败 |
| `RESOURCE_LIMIT_EXCEEDED` | 超出 CPU、内存或存储限制 |
| `VOLUME_ERROR` | 卷操作失败 |
## 环境变量
| 变量 | 描述 |
| -------------------- | --------------- |
| `MODAL_TOKEN_ID` | Modal API 令牌 ID |
| `MODAL_TOKEN_SECRET` | Modal API 令牌密钥 |
***
[连接这些文档](/use-these-docs) 到 Claude、VSCode 等，通过 MCP 获取实时答案。
[在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/javascript/integrations/providers/modal.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。