# @draht/pods 中文文档

规范地址：https://npmcn.com/package/%40draht/pods/

版本：2026\.11\.5
npm 元数据更新时间：2026-11-06T09:11:46.127Z
中文译文更新时间：2026-11-13T03:56:26.801Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40draht/pods
原文对照：https://npmcn.com/package/%40draht/pods/?lang=original
源码仓库：https://github.com/draht-dev/draht

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：234 kB，43 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：^22\.23\.4 \|\| ^24\.22\.1 \|\| ^26\.12\.1
- 运行依赖：2 个
- 首次发布：2026-03-02T18:10:04.691Z
- 最新版本发布：2026-11-06T09:11:45.910Z
- 近 30 天下载量：2360（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：50（近 12 个月 50 个）

## 中文简介

在 GPU 吊舱上管理 vLLM 部署的 CLI 工具

## 安装

```sh
npm install @draht/pods
```

也可以使用：`pnpm add @draht/pods`、`yarn add @draht/pods`、`bun add @draht/pods`

## README

# @draht/pods (英语)

在GPU吊舱上部署和管理LLMS,为代理工作量配置自动vLLM.

## 安装

```bash
bun add -g @draht/pods
```

## 什么鬼东西?

`draht-pods` 简化远程GPU吊舱上运行的大型语言模型. 自动:

-   在新鲜的 Ubuntu 舱上设置 vLLM
-   配置调用代理模型的工具( Quen, GPT- OSS, GLM等)
-   以“ 智能” GPU 分配方式管理同一舱上的多个模型
-   为每个模型提供 OpenAI 兼容的 API 端点
-   包括一个带有文件系统工具用于测试的交互式代理

## 快速启动

```bash
# Set required environment variables
export HF_TOKEN=your_huggingface_token      # Get from https://huggingface.co/settings/tokens
export DRAHT_API_KEY=your_api_key              # Any string you want for API authentication

# Setup a DataCrunch pod with NFS storage (models path auto-extracted)
draht-pods pods setup dc1 "ssh root@1.2.3.4" \
  --mount "sudo mount -t nfs -o nconnect=16 nfs.fin-02.datacrunch.io:/your-pseudo /mnt/hf-models"

# Start a model (automatic configuration for known models)
draht-pods start Qwen/Qwen2.5-Coder-32B-Instruct --name qwen

# Send a single message to the model
draht-pods agent qwen "What is the Fibonacci sequence?"

# Interactive chat mode with file system tools
draht-pods agent qwen -i

# Use with any OpenAI-compatible client
export OPENAI_BASE_URL='http://1.2.3.4:8001/v1'
export OPENAI_API_KEY=$DRAHT_API_KEY
```

## 先决条件

-   节点.js 18+
-   拥抱 面相符 (用于模型下载)
-   GPU 调用 :
    -   乌邦图22.04或24.04
    -   SSH 根访问
    -   安装 NVIDIA 驱动程序
    -   模型的持续存储

## 支持供应商

### 主要支助

**数据搜索** - 共享模型存储的最佳方法

-   同一区域多个吊舱的NFS卷
-   模型下载一次, 随处使用
-   团队的理想或多项实验

**运行Pod** - 长期保存良好

-   网络量持续独立
-   无法同时共享运行中的 pocks
-   适合单波段工作流程

### 也用过

-   Vast.ai(锁定在特定机器上的数量)
-   Prime Intellect( 无持续存储)
-   AWS EC2( 带有 EFS 设置)
-   任何带有 NVIDIA GPU、 CUDA 驱动器和 SSH 的 Ubuntu 机器

## 图标

### 方案管理

```bash
draht-pods pods setup <name> "<ssh>" [options]        # Setup new pod
  --mount "<mount_command>"                   # Run mount command during setup
  --models-path <path>                        # Override extracted path (optional)
  --vllm release|nightly|gpt-oss              # vLLM version (default: release)

draht-pods pods                                       # List all configured pods
draht-pods pods active <name>                         # Switch active pod
draht-pods pods remove <name>                         # Remove pod from local config
draht-pods shell [<name>]                             # SSH into pod
draht-pods ssh [<name>] "<command>"                   # Run command on pod
```

**说明**: 当使用时 `--mount`,模型路径会自动从挂载命令的目标目录中取出. 你们只需要 `--models-path` 如果没有使用 `--mount` 或覆盖已提取路径.

#### vLLM 版本选项

-   `release` (默认):稳定 vLLM 发布,向大多数用户推荐
-   `nightly`: 最新 vLLM 特性, GLM- 4.5 等最新模型所需
-   `gpt-oss`: 只用于 OpenAI 的 GPT- OSS 模型的特殊构建

### 模型管理

```bash
draht-pods start <model> --name <name> [options]  # Start a model
  --memory <percent>      # GPU memory: 30%, 50%, 90% (default: 90%)
  --context <size>        # Context window: 4k, 8k, 16k, 32k, 64k, 128k
  --gpus <count>          # Number of GPUs to use (predefined models only)
  --pod <name>            # Target specific pod (overrides active)
  --vllm <args...>        # Pass custom args directly to vLLM

draht-pods stop [<name>]          # Stop model (or all if no name given)
draht-pods list                   # List running models with status
draht-pods logs <name>            # Stream model logs (tail -f)
```

### 代理聊天接口( C)

```bash
draht-pods agent <name> "<message>"               # Single message to model
draht-pods agent <name> "<msg1>" "<msg2>"         # Multiple messages in sequence
draht-pods agent <name> -i                        # Interactive chat mode
draht-pods agent <name> -i -c                     # Continue previous session

# Standalone OpenAI-compatible agent (works with any API)
draht --base-url http://localhost:8000/v1 --model llama-3.1 "Hello"
draht --api-key sk-... "What is 2+2?"  # Uses OpenAI by default
draht --json "What is 2+2?"            # Output event stream as JSONL
draht -i                                # Interactive mode
```

该代理包括用于文件操作的工具(读取,列表,bash,glob,rg)来测试代理能力,特别是用于代码导航和分析任务.

## 预定义模型配置

`draht-pods` 包括流行代理模型的预定义配置,所以不需要指定 `--vllm` 手动参数. `draht-pods` 还会检查您所选择的模型是否可按 GPU 的数量和可用的 VRAM 运行。 运行 `draht-pods start` 不需要附加参数即可看到可以运行在活性吊舱上的预定义模型列表.

### Quen 模型

```bash
# Qwen2.5-Coder-32B - Excellent coding model, fits on single H100/H200
draht-pods start Qwen/Qwen2.5-Coder-32B-Instruct --name qwen

# Qwen3-Coder-30B - Advanced reasoning with tool use
draht-pods start Qwen/Qwen3-Coder-30B-A3B-Instruct --name qwen3

# Qwen3-Coder-480B - State-of-the-art on 8xH200 (data-parallel mode)
draht-pods start Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8 --name qwen-480b
```

### GPT-OSS 模型

```bash
# Requires special vLLM build during setup
draht-pods pods setup gpt-pod "ssh root@1.2.3.4" --models-path /workspace --vllm gpt-oss

# GPT-OSS-20B - Fits on 16GB+ VRAM
draht-pods start openai/gpt-oss-20b --name gpt20

# GPT-OSS-120B - Needs 60GB+ VRAM
draht-pods start openai/gpt-oss-120b --name gpt120
```

### GLM 模型

```bash
# GLM-4.5 - Requires 8-16 GPUs, includes thinking mode
draht-pods start zai-org/GLM-4.5 --name glm

# GLM-4.5-Air - Smaller version, 1-2 GPUs
draht-pods start zai-org/GLM-4.5-Air --name glm-air
```

### 自定义型号为 -- vllm

对于未在预定义列表中的模型,请使用 `--vllm` 将参数直接传递到 vLLM :

```bash
# DeepSeek with custom settings
draht-pods start deepseek-ai/DeepSeek-V3 --name deepseek --vllm \
  --tensor-parallel-size 4 --trust-remote-code

# Mistral with pipeline parallelism
draht-pods start mistralai/Mixtral-8x22B-Instruct-v0.1 --name mixtral --vllm \
  --tensor-parallel-size 8 --pipeline-parallel-size 2

# Any model with specific tool parser
draht-pods start some/model --name mymodel --vllm \
  --tool-call-parser hermes --enable-auto-tool-choice
```

## DataCrunch 设置

DataCrunch 提供了共享 NFS 存储跨吊舱的最佳经验:

### 1\. 创建共享文件系统(SFS)

-   转到 DataCrunch 仪表板 → 存储 → 创建 SFS
-   选择大小和数据中心
-   注意挂载命令( 例如 ), `sudo mount -t nfs -o nconnect=16 nfs.fin-02.datacrunch.io:/hf-models-fin02-8ac1bab7 /mnt/hf-models-fin02`(中文(简体) )

### 2\. 创建 GPU 实例

-   在 SFS 相同的数据中心创建实例
-   与实例共享 SFS
-   从仪表板获取 SSH 命令

### 3\. 与 draht- pod 设置

```bash
# Get mount command from DataCrunch dashboard
draht-pods pods setup dc1 "ssh root@instance.datacrunch.io" \
  --mount "sudo mount -t nfs -o nconnect=16 nfs.fin-02.datacrunch.io:/your-pseudo /mnt/hf-models"

# Models automatically stored in /mnt/hf-models (extracted from mount command)
```

### 4\. 养恤金

-   模式在重启中持续存在
-   在同一数据中心多个实例之间共享模型
-   下载一次, 随处使用
-   只支付存储费, 不计算下载时间

## 运行Pod 设置

RunPod 以网络音量提供良好的持续存储 :

### 1\. 创建网络量( 可选)

-   转到 RunPod 仪表板 → 存储 → 创建网络音量
-   选择大小和区域

### 2\. 创建 GPU Pod

-   创建 pock 时选择“ 网络音量 ” (如果使用)
-   将您的音量附加到 `/runpod-volume`
-   从 pock 细节获取 SSH 命令

### 3\. 与 draht- pod 设置

```bash
# With network volume
draht-pods pods setup runpod "ssh root@pod.runpod.io" --models-path /runpod-volume

# Or use workspace (persists with pod but not shareable)
draht-pods pods setup runpod "ssh root@pod.runpod.io" --models-path /workspace
```

## 多 GPU 支持

### 自动 GPU 任务

Draht-pods在运行多个模型时,会自动将它们分配到不同的GPU:

```bash
draht-pods start model1 --name m1  # Auto-assigns to GPU 0
draht-pods start model2 --name m2  # Auto-assigns to GPU 1
draht-pods start model3 --name m3  # Auto-assigns to GPU 2
```

### 指定预定义模型的 GPU 计数

对于多个配置的预定义模型,使用 `--gpus` 来控制 GPU 的使用 :

```bash
# Run Qwen on 1 GPU instead of all available
draht-pods start Qwen/Qwen2.5-Coder-32B-Instruct --name qwen --gpus 1

# Run GLM-4.5 on 8 GPUs (if it has an 8-GPU config)
draht-pods start zai-org/GLM-4.5 --name glm --gpus 8
```

如果模型没有被请求的GPU计数的配置,你会看到可用的选项.

### 大型模型的十相平行

对于不符合单个GPU的模型:

```bash
# Use all available GPUs
draht-pods start meta-llama/Llama-3.1-70B-Instruct --name llama70b --vllm \
  --tensor-parallel-size 4

# Specific GPU count
draht-pods start Qwen/Qwen3-Coder-480B-A35B-Instruct-FP8 --name qwen480 --vllm \
  --data-parallel-size 8 --enable-expert-parallel
```

## API 整合

所有模型都暴露出OpenAI相容的端点:

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://your-pod-ip:8001/v1",
    api_key="your-api-key"
)

# Chat completion with tool calling
response = client.chat.completions.create(
    model="Qwen/Qwen2.5-Coder-32B-Instruct",
    messages=[
        {"role": "user", "content": "Write a Python function to calculate fibonacci"}
    ],
    tools=[{
        "type": "function",
        "function": {
            "name": "execute_code",
            "description": "Execute Python code",
            "parameters": {
                "type": "object",
                "properties": {
                    "code": {"type": "string"}
                },
                "required": ["code"]
            }
        }
    }],
    tool_choice="auto"
)
```

## 独立代理CLI

`draht-pods` 包括一个独立的OpenAI兼容代理,可以与任何API合作:

```bash
# Install globally to get draht command
bun add -g @draht/coding-agent

# Use with OpenAI
draht --api-key sk-... "What is machine learning?"

# Use with local vLLM
draht --base-url http://localhost:8000/v1 \
         --model meta-llama/Llama-3.1-8B-Instruct \
         --api-key dummy \
         "Explain quantum computing"

# Interactive mode
draht -i

# Continue previous session
draht --continue "Follow up question"

# Custom system prompt
draht --system-prompt "You are a Python expert" "Write a web scraper"

# Use responses API (for GPT-OSS models)
draht --api responses --model openai/gpt-oss-20b "Hello"
```

该代理支持:

-   持续对话
-   有语法加亮的交互式 TUI 模式
-   代码导航的文件系统工具( 读取、 列表、 bash、 glob、 rg)
-   聊天补全和回复 API 格式
-   自定义系统提示

## 工具调用支持

`draht-pods` 自动配置为已知模型调用解析器的适当工具 :

-   **Quen 型号**数字 : `hermes` 解析器( Quen3- Coder 使用) `qwen3_coder`(中文(简体) )
-   **GLM 模型**数字 : `glm4_moe` 带有推理支持的解析器
-   **GPT-OSS 模型**: 用途 `/v1/responses` 端点,作为工具调用(函数调用OpenAI parlance)目前是一个 [妇女信息方案 `v1/chat/completions` 结束点](https://docs.vllm.ai/projects/recipes/en/latest/OpenAI/GPT-OSS.html#tool-use)。 。 。 .
-   **自定义模型**: 指定为 `--vllm --tool-call-parser <parser> --enable-auto-tool-choice`

要禁用调用的工具 :

```bash
draht-pods start model --name mymodel --vllm --disable-tool-call-parser
```

## 内存和上下文管理

### GPU 内存分配

控制多少 GPU 内存 vLLM 预分配 :

-   `--memory 30%`: 高通币,上下文有限
-   `--memory 50%`: 平衡(默认)
-   `--memory 90%`: 最大上下文, 低货币

### 背景窗口

设置最大输入 + 输出符号 :

-   `--context 4k`: 4 096个令牌共计
-   `--context 32k`:32 768个令牌共计
-   `--context 128k`: 131 072个令牌共计

编码工作量示例:

```bash
# Large context for code analysis, moderate concurrency
draht-pods start Qwen/Qwen2.5-Coder-32B-Instruct --name coder \
  --context 64k --memory 70%
```

**说明**: 当使用时 `--vllm`,则 `--memory`, (中文(简体) ), `--context`,以及 `--gpus` 参数被忽略。 如果你试图一起使用,你会看到一个警告.

## 会话持久性

交互式代理模式( E)`-i`)为每个项目目录保存会话 :

```bash
# Start new session
draht-pods agent qwen -i

# Continue previous session (maintains chat history)
draht-pods agent qwen -i -c
```

会话存储于 `~/.draht/sessions/` 按项目路径排列,包括:

-   完整对话历史
-   工具调用结果
-   Token 使用统计

## 建筑事件系统( E)

代理服务器使用一个基于事件的统一架构,其中所有互动都流经 `AgentEvent` 类型。 这样可以:

-   横跨控制台和 TUI 模式的一致 UI 渲染
-   会话录音和重播
-   API 调用和 UI 更新之间的清洁分隔
-   JSON 方案整合的产出模式

事件会根据模型类型自动转换为相应的API格式(Chat Refults或Resolution).

### JSON 输出模式

使用 `--json` 将事件流输出为 JSONL (JSON Lines) 用于程序消耗的旗帜 :

```bash
draht --api-key sk-... --json "What is 2+2?"
```

每行是一个完整的 JSON 对象,代表一个事件:

```jsonl
{"type":"user_message","text":"What is 2+2?"}
{"type":"assistant_start"}
{"type":"assistant_message","text":"2 + 2 = 4"}
{"type":"token_usage","inputTokens":10,"outputTokens":5,"totalTokens":15,"cacheReadTokens":0,"cacheWriteTokens":0}
```

## 解决问题

### OOM (内存出处) 出错

-   减少 `--memory` 百分比
-   使用更小的模型或量化版本( FP8)
-   减少 `--context` 大小

### 模型不会启动

```bash
# Check GPU usage
draht-pods ssh "nvidia-smi"

# Check if port is in use
draht-pods list

# Force stop all models
draht-pods stop
```

### 工具调用问题

-   不是所有的模型支持工具都可靠地调用
-   尝试不同的解析器 : `--vllm --tool-call-parser mistral`
-   或禁用: `--vllm --disable-tool-call-parser`

### 拒绝模式访问

有些型号(Llama,Mistral)需要休克 面相访问批准. 访问模型页面并点击"请求访问".

### vLLM 数据 构建问题

如果使用 `--vllm nightly` 失败, 请尝试 :

-   使用 `--vllm release` 用于稳定版本
-   检查 CUDA 兼容性 `draht-pods ssh "nvidia-smi"`

### 代理找不到信件

如果代理服务器显示配置而不是您的消息, 请确保引用带有特殊字符的信息 :

```bash
# Good
draht-pods agent qwen "What is this file about?"

# Bad (shell might interpret special chars)
draht-pods agent qwen What is this file about?
```

## 高级使用

### 与多个方案合作

```bash
# Override active pod for any command
draht-pods start model --name test --pod dev-pod
draht-pods list --pod prod-pod
draht-pods stop test --pod dev-pod
```

### 自定义 vLLM 参数

```bash
# Pass any vLLM argument after --vllm
draht-pods start model --name custom --vllm \
  --quantization awq \
  --enable-prefix-caching \
  --max-num-seqs 256 \
  --gpu-memory-utilization 0.95
```

### 监测

```bash
# Watch GPU utilization
draht-pods ssh "watch -n 1 nvidia-smi"

# Check model downloads
draht-pods ssh "du -sh ~/.cache/huggingface/hub/*"

# View all logs
draht-pods ssh "ls -la ~/.vllm_logs/"

# Check agent session history
ls -la ~/.draht/sessions/
```

## 环境变量

-   `HF_TOKEN` - 拥抱 模型下载的面值符
-   `DRAHT_API_KEY` - vLLM 端点的 API 密钥
-   `DRAHT_CONFIG_DIR` - 配置目录( 默认 ): `~/.draht`(中文(简体) )
-   `OPENAI_API_KEY` - 用来 `draht-agent` 否时 `--api-key` 提供

## 许可证

麻省理工学院

## 常见问题

### @draht/pods 是什么？

在 GPU 吊舱上管理 vLLM 部署的 CLI 工具

### 如何安装 @draht/pods？

在项目目录运行 npm install @draht/pods，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 draht-pods，可以用 npx draht-pods 直接运行。

### @draht/pods 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/draht\_\_pods 是否存在。

### @draht/pods 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @draht/pods 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.23\.4 \|\| ^24\.22\.1 \|\| ^26\.12\.1。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @draht/pods 可以商用吗？

@draht/pods 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @draht/pods 的下载量有多少？

根据 npm 官方下载统计，@draht/pods 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,360 次，日均约 79 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @draht/pods 还在维护吗？

最新版本 2026\.11\.5 发布于 2026/11/06（7 天前）；至今共发布 50 个版本，其中过去 12 个月发布了 50 个；首次发布于 2026/03/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。