KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

vllm-ascend-workspace

★ 28 Open GitHub ↗

No description available.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# vllm-ascend-workspace

**中文** | **[English](README.en.md)**

一个可组合的本地开发脚手架，让你在同一个工作区里同时开发 [vLLM](https://github.com/vllm-project/vllm) 和 [vLLM Ascend 插件](https://github.com/vllm-project/vllm-ascend)，并通过内置的 AI Agent 技能自动完成环境初始化、远程 NPU 机器管理、代码同步和服务拉起。

## 这个项目解决什么问题

vLLM Ascend 的开发通常需要在本地编辑代码、在远程昇腾 NPU 服务器上运行测试，同时还要跟踪上游 vLLM 的变化。手动维护这套工作流涉及大量重复的 Git、SSH 和环境配置操作。

`vllm-ascend-workspace` 把这些操作封装成一组 AI Agent 技能，你可以用自然语言让 Agent 代劳，也可以完全忽略这些技能、只把它当作一个普通的多仓库工作区。

## 快速开始

```bash
# 克隆仓库
git clone https://github.com/maoxx241/vllm-ascend-workspace.git
cd vllm-ascend-workspace

# 初始化子模块
git submodule update --init --recursive
```

如果你使用支持 Agent 的 IDE（Cursor、Windsurf 等）或终端工具（Claude Code、Codex CLI 等），可以直接用自然语言完成后续配置：

> "初始化这个工作区，帮我配好 vLLM Ascend 的开发环境。"

Agent 会自动检测你的环境、安装所需工具、配置 Git 远程仓库和 Fork。

## 内置技能

| 技能                       | 用途                                             | 何时使用               |
| ------------------------ | ---------------------------------------------- | ------------------ |
| **repo-init**            | 安装 GitHub CLI、登录 GitHub、初始化子模块、配置 Fork 和远程仓库拓扑 | 首次 clone 后初始化工作区   |
| **machine-management**   | 添加、验证、修复或移除远程昇腾 NPU 服务器及其托管容器                  | 需要配置远程 NPU 开发机时    |
| **session-management**   | 创建、检查、分组和清理隔离 session：本地 worktree、远端容器、状态目录和资源 lease | 多 agent、多任务或 PD 场景并行远端执行时 |
| **remote-toolbox**       | 结构化解析/探测/执行/长任务/同步/服务/产物传输/清理远端容器              | Agent 需要像使用本地工具一样操作远端 session container 时 |
| **remote-code-parity**   | 将本地工作区的完整状态（含未提交的修改）同步到远程容器                    | 在远程机器上运行测试或服务前自动触发 |
| **modelscope**           | 下载、续传、查看进度并 SHA256 校验 ModelScope 模型权重                  | 需要把模型权重下载到明确目录时 |
| **vllm-ascend-serving**  | 在远程容器上一键拉起 vLLM Ascend 推理服务，支持 NPU 探测、自动选卡、增量重启 | 需要在远程机器上起推理服务时     |
| **vllm-ascend-benchmark** | 在远程容器上运行 `vllm bench serve` 性能基准测试，支持多轮预热和统计聚合     | 需要跑吞吐/延迟基准测试或性能回归对比时 |
| **ascend-memory-profiling** | 采集并分析昇腾 NPU 的 HBM 显存占用，按组件拆分并溯源 | 需要分析 vLLM 推理服务的显存占用时 |
| **ascend-profiling-collection** | 采集 Ascend torch profiler：起服务、控制 profile 窗口、运行 workload、远端 analyse 并写 manifest | 需要采集 kernel_details/trace_view 时 |
| **ascend-profiling-analysis** | 分析已采集的 profiler root/manifest，生成 step/layer/operator/cross-rank 诊断报告 | 需要分析 profiling 结果或生成报告时 |
| **curate-workspace-knowledge** | 审核、去重、提升、合并、拒绝或废弃已验证的项目知识候选 | 显式要求沉淀、整理或维护项目知识时 |
| **vllm-ascend-graph-debug** | 定位图编译、捕获、重放及 graph/eager 正确性分歧 | 图模式失败或与 eager 结果不一致时 |
| **vllm-ascend-correctness-validation** | 对比 baseline/candidate、eager/graph、离线/在线和 AISBench 正确性 | 需要精度验证或输出对拍时 |
| **vllm-ascend-change-validation** | 根据代码 diff 生成验证计划并汇总证据和 PR 报告 | 验证工作区变更或 PR 时 |
| **vllm-ascend-performance-regression** | 运行交替 A/B 实验并分析波动和回退阈值 | 判断吞吐或延迟是否回退时 |
| **vllm-ascend-distributed-debug** | 从拓扑、端点、collective 和逐 rank 事件诊断分布式故障 | 故障依赖多卡、多机或 rank 时 |
| **ascend-operator-debug** | 将模型故障缩减为单算子并运行 dtype/shape/layout/mode 矩阵 | 需要最小化算子复现时 |
| **ascend-triton-operator-development** | 从 PyTorch 或 GPU Triton 语义生成首个正确的 Ascend Triton 实现 | 新建或迁移 Triton 算子时 |
| **ascend-triton-kernel-validation** | 检测 PyTorch fallback 并执行显式正确性矩阵 | 验证 Triton 候选实现时 |
| **ascend-triton-kernel-optimization** | 在正确性门禁后执行 profiler 驱动的优化实验 | 优化已正确的 Triton kernel 时 |
| **ascend-triton-workflow** | 编排开发、验证、优化和 Run Manifest 证据 | 交付完整 Triton 算子生命周期时 |
| **vllm-ascend-pd-serving** | 编排 Session Group 上的 prefill/decode、connector、回滚和 KV smoke | 部署 PD 分离服务时 |

所有技能都是**可选的**。你可以只用其中的一部分，也可以完全不用。

## 使用示例

与 Agent 对话时，可以这样说：

```
# 初始化
"帮我初始化一下这个仓库"
"帮我配置一下这个仓库"

# 机器管理
"帮我添加一下这两台服务器，ip 是 x.x.x.1 和 x.x.x.2，密码是 xxxx"
"帮我配置一下这台服务器，ip 是 x.x.x.x，密码是 xxxx"
"帮我删除 x.x.x.x 服务器"

# 代码同步
"帮我同步代码到服务器上并重新编译"

# 模型权重下载
"帮我把 Qwen/Qwen3-32B 从 ModelScope 下载到 /root/Qwen/Qwen3-32B，并查看进度"
"校验一下 /root/Qwen/Qwen3-32B 的 ModelScope 权重"

# 服务拉起（--model 需要指定远程容器上已存在的权重路径，不支持自动下载）
"在 x.x.x.x 上用 /home/weights/Qwen3-32B-W8A8 拉一个 4 卡的推理服务，开 W8A8 量化"
"帮我重启一下 x.x.x.x 的服务，把 max-model-len 改成 8192"
"看下 x.x.x.x 上的服务状态"
"停掉 x.x.x.x 上的服务"

# 性能基准测试
"在 x.x.x.x 上用 Qwen3.5-35B 跑个 benchmark，4 卡，跑 5 组取后 4 组"
"对比一下 main 和这个 PR 的吞吐差异"
```

## 仓库结构

```
.
├── vllm/                  # vLLM 上游（Git 子模块）
├── vllm-ascend/           # vLLM Ascend 插件（Git 子模块）
├── .agents/
│   ├── skills/
│   │   ├── repo-init/             # 工作区初始化技能
│   │   ├── machine-management/    # 远程机器管理技能
│   │   ├── session-management/    # 并行 Session 隔离技能
│   │   ├── remote-toolbox/        # 远端结构化工具面
│   │   ├── remote-code-parity/    # 代码同步技能
│   │   ├── modelscope/            # ModelScope 权重下载与校验技能
│   │   ├── vllm-ascend-serving/   # 服务拉起技能
│   │   ├── vllm-ascend-benchmark/ # 性能基准测试技能
│   │   ├── ascend-memory-profiling/ # 显存 profiling 技能
│   │   ├── ascend-profiling-collection/ # torch profiler 采集技能
│   │   ├── ascend-profiling-analysis/ # profiling 分析报告技能
│   │   └── curate-workspace-knowledge/ # 显式知识整理技能
│   ├── lib/               # 共享本地状态库
│   └── scripts/           # 共享辅助脚本
├── .cursor/rules/         # Cursor IDE 专用规则
├── .trae/                 # TRAE IDE 专用规则与技能
├── AGENTS.md              # 跨工具 Agent 指令（AI Agent 读这个）
├── CLAUDE.md              # Claude Code 指令入口
└── README.md              # 你正在看的这个文件
```

## 设计原则

- **不强制任何流程** — 所有技能都可选，开发者自由选择使用哪些部分。
- **本地状态不入库** — 用户特定的远程仓库、认证信息、机器配置等只存在于本地未跟踪的 `.vaws-local/` 目录中。
- **统一 Agent 身份** — 项目初始化会静默持久化 UUID4，并可由用户选择统一别名；新容器、服务目录和服务环境使用该别名，已有资源不被重命名。
- **并行任务隔离** — 远端并行执行优先使用 session：每个任务有独立本地 worktree、远端容器、状态目录和资源 lease。
- **可选资源协调** — 独立 Agent 可通过宿主机 `/tmp` 中的共享 SQLite 队列发布 NPU 意向、排队和人工占用窗口；该协议只做君子协作，不强制拦截既有任务流程。
- **远端操作结构化** — Agent 面向远端容器优先使用 remote toolbox，产出 JSON、可观测日志、可恢复 artifact manifest 和可清理状态。
- **子模块指向社区** — `.gitmodules` 始终指向 `vllm-project` 的官方仓库，个人 Fork 是本地运行时配置。
- **Agent 驱动，但不依赖 Agent** — 所有操作都可以手动完成，Agent 只是让流程更方便。

## 推荐的远程仓库拓扑

技能会推荐以下拓扑结构，但不强制要求：

| 仓库            | `origin`    | `upstream`                       |
| ------------- | ----------- | -------------------------------- |
| workspace     | 你的 Fork（可选） | `maoxx241/vllm-ascend-workspace` |
| `vllm`        | 你的 Fork（可选） | `vllm-project/vllm`              |
| `vllm-ascend` | 你的 Fork     | `vllm-project/vllm-ascend`       |

## 多工具支持

本仓库支持主流 AI 编程工具：

| 文件               | 覆盖工具                                    |
| ---------------- | ---------------------------------------- |
| `AGENTS.md`      | Codex CLI、GitHub Copilot、Cursor、TRAE、OpenCode |
| `CLAUDE.md`      | Claude Code                              |
| `.cursor/rules/` | Cursor                                   |
| `.trae/`         | TRAE                                     |

## Roadmap

### 已完成

- [x] **repo-init** — 工作区初始化：GitHub CLI 安装、认证、子模块、Fork 与远程仓库拓扑配置
- [x] **machine-management** — 远程机器管理：添加、验证、修复、移除昇腾 NPU 服务器及托管容器
- [x] **remote-code-parity** — 代码同步：将本地完整工作区状态（含未提交修改）同步到远程容器
- [x] **vllm-ascend-serving** — 服务拉起：支持空闲 NPU 检测、空闲端口检测，一键拉起 vLLM Ascend 推理服务
- [x] **vllm-ascend-benchmark** — 在线性能基准测试：支持单轮/多轮（warm-service）模式、预热轮剔除、统计聚合，多状态回归对比由 Agent 编排
- [x] **ascend-memory-profiling** — 显存 profiling：采集并分析 HBM 显存占用，按固定开销、模型权重、KV cache、HCCL、激活、runtime 拆分，支持 msprof 组件级归因

### 计划中

- [ ] **精度测试与 aisbench 集成** — 基于 aisbench 的自动化评测，支持 HTML 报告自动分析、系统调度评估及 DP 均衡度分析
- [ ] **性能 Profiling 分析** — 自动分析模型主要算子耗时，热点算子 AIC/AIV/MTE2 ratio 分析，AICPU 算子识别，host bound 识别与诊断
- [ ] **同步打断优化** — 针对具体 case 提供异步拷贝掩盖方案，减少同步等待开销
- [ ] **计算图分析** — 构建模型计算图，提供基于计算图的理论性能评估报告及优化方案
- [ ] **外置知识库接入** — 接入外部知识库，扩展 Agent 的能力边界

## 许可证

本脚手架仓库的许可证独立于子模块。`vllm/` 和 `vllm-ascend/` 各自遵循其上游项目的许可证。

vllm-ascend-workspace

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README