快速入门

快速入门

本指南帮助你在 5 分钟内部署 HeteroFlow V2 并运行第一个 GPU 推理服务。1

前提条件

• 一台 Linux 服务器（管理节点）
• 至少一台配备 GPU 的 Linux 服务器（计算节点）
• 网络互通（管理节点 ↔ 计算节点）
• Go 1.22+、Node.js 18+（如需编译前端）

第一步：编译部署 Server

在管理节点上执行：

# 克隆项目
git clone https://gitee.com/heteroflow/HeteroFlow.git
cd HeteroFlow

# 编译后端
cd v2/cmd && go build -o server . && cd ../..

# 配置
cp config.yaml.example config.yaml
# 编辑 config.yaml，设置数据库、jwt_secret、agent_secret

第二步：启动 Server

./server

Server 启动后：

• 后端 API：http://localhost:3333
• 前端界面：http://localhost:5173

第三步：部署 Agent

在 GPU 计算节点上执行一键部署脚本：

curl -fsSL http://<server-ip>:5173/deploy-agent-all-in-one.sh | bash
export EXTENDER_URL="http://<server-ip>:3333"

Agent 启动后会自动：

• 检测 GPU 类型和数量
• 上报系统资源信息
• 注册到 Server
• 开始心跳

第四步：创建推理服务

通过 Web UI 或 API 创建推理服务：

Web UI 方式：

1. 访问 http://localhost:5173，使用 admin/admin123 登录

2. 点击左侧「推理服务」

3. 点击「创建推理服务」

4. 填写服务名称、Docker 镜像、GPU 数量等

5. 点击「创建」

API 方式：

# 登录获取 Token
TOKEN=$(curl -s http://localhost:3333/api/v1/auth/login \
  -d ''{"username":"admin","password":"admin123"}'' | jq -r '.data.token')

# 创建推理服务
curl -X POST http://localhost:3333/api/v1/task-groups \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d ''{
    "name": "my-qwen-service",
    "image": "vllm/vllm-openai:latest",
    "gpu_required": 1,
    "model_path": "/data/models/qwen-0.5b",
    "port_mapping": "8000",
    "enable_api": true
  }''

第五步：调用推理 API

服务启动后，使用 OpenAI 兼容 API 调用：

curl http://localhost:3333/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d ''{
    "model": "my-qwen-service",
    "messages": [{"role": "user", "content": "你好"}]
  }''

Python SDK 调用：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3333/v1",
    api_key="sk-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
)

response = client.chat.completions.create(
    model="my-qwen-service",
    messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)

其他操作

提交普通 GPU 任务

curl -X POST http://localhost:3333/api/v1/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -d ''{
    "name": "training-job",
    "image": "pytorch/pytorch:2.0",
    "command": ["python", "train.py"],
    "priority": "high",
    "resources": {
      "gpu_type": "nvidia",
      "gpu_count": 2,
      "gpu_memory_mb": 16384
    }
  }''

查看集群状态

# 查看节点列表
curl http://localhost:3333/api/v1/nodes

# 查看推理服务
curl http://localhost:3333/api/v1/task-groups

# 查看任务列表
curl http://localhost:3333/api/v1/tasks

下一步

• [用户指南](./user-guide) — 详细使用说明
• [推理服务](../features/inference-service) — 推理服务详解
• [部署指南](../deployment/server-setup) — 生产环境部署
• [API 参考](../api-reference/auth-api) — 完整 API 文档

<!-- SYNCPROOF030011 -->