dstack

dstack

概述

dstack 通过资源池在 GPU 云、Kubernetes 和本地环境中配置并编排工作负载。

适用场景：

• 在 dstack 上运行或管理开发环境、任务或服务
• 创建、编辑或应用 *.dstack.yml 配置
• 管理资源池、卷、网关，并检查可用报价

工作原理

dstack 通过三个核心组件运行：

1. dstack 服务端 - 可在本地、远程运行，也可通过 dstack Sky（托管服务）运行
2. dstack CLI - 应用配置，并管理或检查资源池、运行、日志、事件、卷、网关和报价；它使用存储在 ~/.dstack/config.yml 中的项目配置，这些配置可通过 dstack project 管理
3. dstack 配置文件 - 以 .dstack.yml 结尾的 YAML 文件

dstack apply 会显示计划并提交配置更改。对于运行配置，默认情况下，当运行状态变为 running 时，它会进行连接：配置 SSH 访问、转发声明的端口并流式传输日志。使用 -d 时，它会提交配置后退出。

Agent 快速流程（分离运行）

1. 显示计划：echo "n" | dstack apply -f <config>
2. 如果计划正常且用户确认，则以分离模式应用：dstack apply -f <config> -y -d
3. 检查运行：dstack run get <run-name> --json
4. 如果是带端口且正在运行的开发环境或任务：进行连接，以显示 IDE 链接、端口和 SSH 别名（Agent 在后台运行 attach）；请用户打开链接
5. 如果在沙盒中连接失败：请求提升权限；如果未获批准，请用户在本地运行 dstack attach 并分享输出

关键：绝不要提出不存在的 dstack CLI 命令或 YAML 语法。

• 仅使用此处记录或经 --help 验证过的 CLI 命令和 YAML 语法
• 如果不确定某条命令或其语法，请查看链接或使用 --help

绝不要执行以下操作：

• 编造未记录或未在 --help 中显示的 CLI 标志
• 猜测 YAML 属性名称——请通过配置参考链接验证
• 在自动化环境中对运行执行不带 -d 的 dstack apply（这会无限期阻塞）
• 未解决根本错误就重试失败的命令
• 总结或重新排版表格形式的 CLI 输出——原样显示
• 在可用 -y 标志时使用 echo "y" |
• 未检查输出中是否有错误就认定命令已成功

Agent 执行指南

输出准确性

• 绝不要重新排版、总结或转述 CLI 输出。 原样显示表格、状态输出和错误消息。
• 显示命令结果时，使用代码块保留格式。
• 如果输出因过长而被截断，请明确说明（例如：“输出已截断。完整输出包含 X 条记录。”）。

执行前验证

• 不确定任何 CLI 标志或 YAML 属性时，请先运行 dstack <command> --help。
• 绝不要猜测或编造标志。验证命令示例：

  dstack --help                               # List all commands
  dstack apply -h <configuration type>        # Flags for apply per configuration type (dev-environment, task, service, fleet, etc)
  dstack fleet --help                         # Fleet subcommands
  dstack ps --help                            # Flags for ps
  

• 如果命令或标志未记录，则表示它不存在。

命令运行时间和确认处理

在前台无限期持续输出的命令：

• dstack attach
• 对运行任务执行不带 -d 的 dstack apply
• dstack ps -w

Agent 应避免阻塞：使用 -d、超时，或在后台执行 attach。需要 attach 时，默认在后台运行（nohup ...），但除非用户要求实时前台会话，否则向用户简单称其为“attach”。

以编程方式等待特定运行时，使用 dstack run get <run-name> --json 并读取顶层的 status。运行状态为 pending、submitted、provisioning、running、terminating、 terminated、failed 和 done；最后三个是终止状态。当运行达到后续操作所需的状态或终止状态时，停止等待。 绝不要解析或 grep 人类可读的 dstack ps 输出；其状态列可能会显示诸如 no offers 的作业消息。

**所有其他命令：**使用 10-60s 的超时时间。大多数命令都能在此时间范围内完成。等待时，请监控输出——其中可能包含需要处理的错误、警告或提示。

确认处理：

• dstack apply、dstack stop、dstack fleet delete 需要确认
• 用户已批准时，使用 -y 标志自动确认
• 对于 dstack stop，用户确认后始终使用 -y，以避免交互式提示
• 使用 echo "n" | 预览 dstack apply 计划而不执行（避免使用 echo "y" |，优先使用 -y）

最佳实践：

• 优先修改配置文件，而不是向 dstack apply 传递参数（例外情况除外）
• 用户确认删除或停止操作后，使用 -y 标志跳过确认提示

分离运行后的后续操作（使用 -d 后）

使用 -d（开发环境、任务、服务）提交运行后，首先判断提交是否失败。如果 apply 输出显示错误（验证错误、无可用资源等），请停止操作并说明错误。

如果运行已提交，使用 dstack run get <run-name> --json 检查，然后引导用户完成相关后续步骤： 如果需要询问下一步操作，请明确说明 dstack 步骤和命令（避免含糊提问）。与用户交流时，将该操作称为“attach”（不要称为“后台 attach”）。

• **监控状态：**报告当前状态，并询问是否继续监控。如果继续监控，则每隔 10-20 秒轮询一次 dstack run get <run-name> --json，直到运行达到后续操作所需的状态或终止状态。
• **运行后 attach：**对于 Agent，默认在后台运行 attach，以免会话阻塞。使用它获取 IDE 链接/SSH 别名或启用端口转发；向用户描述该操作时，只需称为“attach”。
• **带端口的开发环境或任务：**运行达到 running 后，执行 attach 以显示 IDE 链接/端口转发/SSH 别名，然后询问是否打开 IDE 链接。未经明确批准，绝不要打开链接。
• **服务：**优先使用服务端点。只有用户明确需要端口转发或完整重放日志时才执行 attach。
• **不带端口的任务：**默认使用 dstack logs 查看进度；只有需要完整重放日志时才执行 attach。

附加行为（阻塞与非阻塞）

dstack attach 会一直运行，直到被中断，并阻塞终端。**Agent 必须避免无限期阻塞。**如果只需短暂附加，请使用超时来捕获初始输出（IDE 链接、SSH 别名），然后分离。

注意：dstack attach 会在 ~/.dstack/ssh/config 下写入 SSH 别名信息（并可能更新 ~/.ssh/config），以便启用 ssh <run name>、IDE 连接、端口转发和实时日志（dstack attach --logs）。如果沙盒无法写入这些位置，就不会创建别名。

**权限防护：**如果 dstack attach 因沙盒权限而失败，请请求提升权限，以便在沙盒外运行。如果未获批准，或附加仍然失败，请让用户在本地运行 dstack attach，并分享 IDE 链接/SSH 别名输出。

后台附加（Agent 的默认非阻塞方式）：

nohup dstack attach <run name> --logs > /tmp/<run name>.attach.log 2>&1 & echo $! > /tmp/<run name>.attach.pid

然后读取输出：

tail -n 50 /tmp/<run name>.attach.log

只有在用户提出要求时才提供实时跟随：

tail -f /tmp/<run name>.attach.log

停止后台附加（首选方式）：

kill "$(cat /tmp/<run name>.attach.pid)"

如果 PID 文件缺失，请改用特定匹配项（避免终止所有附加进程）：

pkill -f "dstack attach <run name>"

**这样做的好处：**它能保持附加会话运行（包括端口转发），同时让 Agent 保持可用。IDE 链接和 SSH 说明会显示在日志文件中——展示这些信息，并仅在获得明确批准后询问是否打开链接（在 macOS 上使用 open "<link>"，在 Linux 上使用 xdg-open "<link>"）。

如果后台附加在沙盒中失败（因写入 ~/.dstack 或 ~/.ssh 的权限不足，或发生超时），请请求提升权限，以便在沙盒外运行附加。如果未获批准，请让用户在本地运行附加，并分享 IDE 链接/SSH 别名。

解读用户请求

**“运行某些内容”：**当用户要求运行工作负载（开发环境、任务、服务）时，请使用相应的配置执行 dstack apply。注意：dstack run 仅支持使用 dstack run get --json 获取运行详情，不能启动工作负载。

**“连接到”或“打开”开发环境：**如果开发环境已在运行，请使用 dstack attach <run name> --logs（Agent 默认会在后台运行此命令）展示 IDE URL（cursor://、vscode:// 等）和 SSH 别名。如果在沙盒中附加失败，请请求提升权限，或让用户在本地运行附加并分享链接。

多节点任务和多副本服务

除非使用多节点任务（参见 ### 2. Tasks）或多副本服务（参见 ### 3. Services），否则任务和服务都在单个节点上运行。因此，dstack logs <run name>、dstack attach <run name> 和 ssh <run name> 默认会连接到第一个副本/作业。

• 在多节点任务中，每个节点都会运行自己的作业，编号按节点组顺序从 0 开始。使用 dstack logs <run name> --job 1 或 dstack attach <run name> --job 1 指定节点。
• 在多副本服务中，副本会按副本组顺序从 0 开始编号。使用 dstack logs <run name> --replica 1 或 dstack attach <run name> --replica 1 指定副本。
• 使用非零 --job 或 --replica 附加时，会创建 SSH 别名 ssh <run name>-<job num>-<replica num>。

配置类型

dstack 支持运行配置（开发环境、任务和服务）以及基础设施配置（集群、卷和网关）。配置文件可以命名为 <name>.dstack.yml，也可以直接命名为 .dstack.yml。

通用参数： 所有运行配置（开发环境、任务和服务）都支持许多参数，包括：

• Git 集成： 自动克隆仓库（repo）或挂载现有仓库（repos）
• 文件上传： 上传本地文件（files；示例请参阅概念文档）
• Docker 支持： 使用自定义 Docker 镜像（image）；如果要在容器内使用 Docker，请设置 docker: true（仅适用于基于 VM 的后端）
• 环境： 设置环境变量（env），通常通过 .envrc 设置。也支持密钥，但较少使用。
• 存储： 持久化网络卷（volumes），指定磁盘大小
• 资源： 定义 GPU、CPU、内存和磁盘要求

最佳实践：

• 建议为配置设置 name 属性，以便于管理
• 如果配置需要凭据（API 密钥、令牌），请在 env 部分仅列出环境变量名称（例如 - HF_TOKEN），而非具体值。建议将实际值存储在配置旁的 .envrc 文件中，并通过 source .envrc && dstack apply 应用。
• 在运行配置中，python 和 image 互斥。如果设置了 image，请勿设置 python。
• commands 条目会用 && 拼接成一行 shell 命令，因此多行 shell 命令（例如 heredoc）应放在单个条目中（使用 | 块）。如果 heredoc 在某个条目末尾结束，它会吞掉其后的所有条目，并导致运行以 0 退出且不执行这些条目。条目末尾的 # comment 也有相同问题，它会注释掉该行剩余部分。

files 和 repos 的使用原则

仅当用户希望在运行中使用本地文件或仓库文件时，才使用 files 和 repos。

• 如果用户要求在运行中使用项目代码、数据或配置，则根据情况添加 files 或 repos。
• 如果完全不清楚是否需要挂载文件或仓库，请提出一个明确的澄清问题，或默认不挂载。

files 指南：

• 本地项目文件可以使用相对路径，且优先使用相对路径。
• 相对路径形式的 files 路径会放在运行的 working_dir 下（使用默认值或用户设置的值）。

repos、镜像和工作目录指南：

• 使用非默认 Docker 镜像时，建议为 repos 指定明确的绝对挂载目标（例如 .:/dstack/run）。
• 设置明确的仓库挂载路径时，也要将 working_dir 设置为相同路径。
• 原因：自定义镜像可能具有不同的非空默认工作目录，将仓库挂载到非空路径可能会失败。
• 使用 dstack 默认镜像时，默认 working_dir 已经是 /dstack/run。

1. 开发环境

适用场景： 配合 IDE（VS Code、Cursor 等）进行交互式开发。

type: dev-environment
name: cursor

python: "3.12"
ide: vscode

resources:
  gpu: 80GB

概念文档 | 配置参考

2. 任务

适用场景： 批处理作业、训练运行、微调、Web 应用以及任何可执行工作负载。

主要功能： 分布式训练（多节点）以及 Web 应用的端口转发。

type: task
name: train

python: "3.12"
env:
  - HUGGING_FACE_HUB_TOKEN
commands:
  - uv pip install -r requirements.txt
  - uv run python train.py
ports:
  - 8501  # Optional: expose ports for web apps

resources:
  gpu: A100:40GB:2

端口转发： 指定 ports 后，dstack apply 会在连接期间将这些端口转发到 localhost。使用 dstack attach <run name> 重新连接并恢复端口转发。运行名称会成为 SSH 别名（例如 ssh <run name>），可用于直接访问。

多节点任务： 设置 nodes 可在多个节点上运行任务；也可以使用 groups 定义节点组，每组可分别设置自己的 nodes 数量、resources、commands 和 ports（groups 与顶层 nodes 互斥）。需要支持节点间通信的集群（参见集群中的 placement: cluster）。

概念文档 | 配置参考

3. 服务

适用场景： 将模型或 Web 应用部署为生产环境端点。

主要功能： 兼容 OpenAI 的模型服务、自动扩缩容（RPS/队列）、支持 HTTPS 的自定义网关。

type: service
name: llama31

python: "3.12"
env:
  - HF_TOKEN
commands:
  - uv pip install vllm
  - uv run vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct
port: 8000
model: meta-llama/Meta-Llama-3.1-8B-Instruct

resources:
  gpu: 80GB
  disk: 200GB

服务端点：

• 不使用网关：<server URL>/proxy/services/<project name>/<run name>/
• 使用网关：https://<run name>.<gateway domain>/
• 身份验证：除非 auth 为 false，否则服务请求中需包含 Authorization: Bearer <user token>。
• 模型端点：如果设置了 model，dstack run get <run name> --json 返回的 service.model.base_url 即为模型端点。对于兼容 OpenAI 的模型（默认格式，除非另行设置），该端点为 service.url + /v1。
• 示例（使用网关）：

  curl -sS -X POST "https://<run name>.<gateway domain>/v1/chat/completions" \
    -H "Authorization: Bearer <user token>" \
    -H "Content-Type: application/json" \
    -d '{"model":"<model name>","messages":[{"role":"user","content":"Hello"}],"max_tokens":64}'
  

多副本服务： 设置 replicas 以运行多个副本，或使用 groups 定义副本组，每组都有自己的 replicas 数量、resources 和 commands（groups 与顶层 replicas 不能同时使用）。如果副本需要互连（例如 PD 解耦），服务必须在设置了 placement: cluster 的集群上运行。

概念文档 | 配置参考

4. 资源池

适用场景： 为工作负载预配基础设施、管理本地 GPU 服务器、创建自动扩缩容实例池。

type: fleet
name: my-fleet
nodes: 0..2

resources:
  gpu: 24GB..
  disk: 200GB

spot_policy: auto # other values: spot, on-demand
idle_duration: 5m

按需预配： 当 nodes 为范围（例如 0..2）时，dstack 会创建模板，并在最小值和最大值范围内按需预配实例。使用 idle_duration 终止空闲实例。

分布式工作负载： 对于用于需要节点间网络连接的多节点任务的资源池，请使用 placement: cluster。

SSH 资源池（本地部署或预先配置）：

type: fleet
name: on-prem-fleet

ssh_config:
  user: ubuntu
  identity_file: ~/.ssh/id_rsa
  hosts:
    - 192.168.1.10
    - 192.168.1.11

概念文档 | 配置参考

5. 卷

适用场景： 为数据集、模型检查点和训练产物提供持久存储。

type: volume
name: my-volume

backend: aws
region: us-east-1

resources:
  disk: 500GB

实例卷（本地、临时，通常为可选项）：

type: dev-environment
# ... other config
volumes:
  - instance_path: /dstack-cache/pip
    path: /root/.cache/pip
    optional: true
  - instance_path: /dstack-cache/huggingface
    path: /root/.cache/huggingface
    optional: true

挂载卷： 在开发环境、任务和服务中使用 volumes。网络卷独立持久化；实例卷的生命周期与实例绑定。

概念文档 | 配置参考

6. 网关

适用场景： 基本服务端点可以不使用网关。如果服务使用自动扩缩容或速率限制、需要在自定义域名上启用 HTTPS、需要 WebSocket，或无法使用服务器代理路径前缀，则必须使用网关。

type: gateway
name: my-gateway

backend: aws
region: us-east-1
domain: example.com

概念文档 | 配置参考

必备 CLI 命令

应用配置

重要行为：

• dstack apply 会显示包含预估费用的计划，并可能要求确认
• 在附加模式（默认模式）下，终端会阻塞并显示输出
• 在分离模式（-d）下，命令会提交并退出，不会附加到运行中任务

应用运行配置（开发环境、任务、服务）的工作流：

1. 显示计划：

   echo "n" | dstack apply -f config.dstack.yml
   

   显示完整输出，包括优惠表和费用估算。不要总结或重新排版。

2. 等待用户确认。 遇到以下情况时不要继续：

   • 输出显示“No offers found”或类似错误
   • 输出显示验证错误
   • 用户尚未明确确认

3. 执行（仅在用户确认后）：

   dstack apply -f config.dstack.yml -y -d
   

4. 验证应用状态：

   dstack run get <run-name> --json
   

基础设施（资源池、卷、网关）的工作流：

1. 显示计划：

   echo "n" | dstack apply -f infra.dstack.yml
   

   显示完整输出。不要总结或重新排版。

2. 等待用户确认。

3. 执行：

   dstack apply -f infra.dstack.yml -y
   

4. 验证： 分别使用 dstack fleet、dstack volume 或 dstack gateway。

Fleet 管理

# Create/update fleet
dstack apply -f fleet.dstack.yml

# List fleets
dstack fleet

# Get fleet details
dstack fleet get my-fleet

# Get fleet details as JSON (for troubleshooting)
dstack fleet get my-fleet --json

# Delete entire fleet (use -y when user already confirmed)
dstack fleet delete my-fleet -y

# Delete specific instance from fleet (use -y when user already confirmed)
dstack fleet delete my-fleet -i <instance num> -y

主机 GPU 驱动： 对于 NVIDIA、AMD 和 Tenstorrent，基于 VM 的后端和 SSH Fleet 会在 instances[].gpu_driver.version 中报告主机 GPU 驱动版本。实例处于 idle 或 busy 状态后，可通过 dstack fleet get my-fleet --json 获取该信息。当你不确定主机驱动是否与工作负载兼容时，这很有用。

监控运行

# List all runs
dstack ps

# Verbose output with full details
dstack ps -v

# JSON output (for troubleshooting/scripting)
dstack ps --json

# Get specific run details as JSON
dstack run get my-run-name --json

连接到运行

# Attach and replay logs from start (preferred, unless asked otherwise)
dstack attach my-run-name --logs

# Attach without replaying logs (restores port forwarding + SSH only)
dstack attach my-run-name

查看日志

# Stream logs (tail mode)
dstack logs my-run-name

# Debug mode (includes additional runner logs)
dstack logs my-run-name -d

# Fetch logs from specific replica (multi-node runs)
dstack logs my-run-name --replica 1

# Fetch logs from specific job
dstack logs my-run-name --job 0

停止运行

# Stop specific run (use -y after user confirms)
dstack stop my-run-name -y

# Abort (force stop)
dstack stop my-run-name --abort

列出报价

报价表示符合资源要求的可用实例配置。如果省略 --fleet，dstack offer 会检查所有已配置的后端。列出报价不会创建容量；提交运行仍需要至少一个能够配置或复用匹配实例的 Fleet。使用 --fleet 查看特定 Fleet 提供的报价。

# Filter by specific backend
dstack offer --backend aws

# Filter by GPU type
dstack offer --gpu A100

# Filter by GPU memory
dstack offer --gpu 24GB..80GB

# Combine filters
dstack offer --backend aws --gpu A100:80GB

# Limit to a specific fleet
dstack offer --fleet my-fleet

# Combine offers from multiple fleets
dstack offer --fleet my-fleet --fleet other-fleet

# JSON output (for troubleshooting/scripting)
dstack offer --json

使用一个 --fleet 时，dstack offer 会显示该 Fleet 提供的报价。使用多个 --fleet 时，它会汇总所选 Fleet 提供的报价。相同的后端报价只显示一次，而匹配的现有实例则会单独显示。

最大报价数： 默认情况下，dstack offer 会返回前 N 个报价（输出也会包含总数）。使用 --max-offers N 可提高上限。

分组： 要汇总所有报价，建议使用 --group-by gpu，而非 --max-offers。其他支持的字段包括 backend、region 和 count；region 需要与 backend 一起使用。

故障排除

诊断 dstack 工作负载或基础设施问题时：

1. 使用 JSON 输出进行详细检查：

   dstack fleet get my-fleet --json
   dstack run get my-run --json
   dstack ps -n 10 --json
   dstack offer --json
   

2. 检查详细的运行状态：

   dstack ps -v
   

3. 查看调试输出中的日志：

   dstack logs my-run -d
   

4. 连接并重放日志：

   dstack attach my-run --logs
   

常见问题：

• 没有报价： 检查 dstack offer；如果要提交运行，请确保至少有一个 Fleet 能够配置或复用匹配的实例
• 没有 Fleet： 确保已创建至少一个 Fleet
• 配置错误： 验证 YAML 语法；检查 dstack apply 输出中的具体错误
• 配置超时： 使用 dstack run get <run-name> --json 检查运行；考虑使用竞价实例而非按需实例
• 连接问题： 验证服务状态，检查身份验证，并确保可以访问后端网络

发生错误时：

1. 原样显示完整错误消息
2. 在解决错误之前，切勿重试相同命令
3. 参考故障排除指南获取指引

其他资源

核心文档：

• 概览
• 安装
• 快速入门

其他概念：

• 密钥
• 项目
• 指标
• 事件

指南：

• CLI 与 API
• 服务部署

特定加速器示例：

• AMD
• Google TPU
• Tenstorrent

完整文档： https://dstack.ai/llms-full.txt