98 lines
4.8 KiB
Markdown
98 lines
4.8 KiB
Markdown
# 信创模盒适配智能体（ModelHub XC Adapt Agent）
|
||
|
||
按《信创模盒适配智能体提交说明》（https://www.modelhub.org.cn/#/docs/6 ）实现的策略镜像：
|
||
自动从社区模型库挑选候选模型，按卡批量提交国产算力适配验证任务。
|
||
|
||
## 一、平台契约对照
|
||
|
||
| 平台要求 | 本仓库实现 |
|
||
|---|---|
|
||
| 仓库根目录 Dockerfile | `Dockerfile`，基于 `modelhubxc-4pd.tencentcloudcr.com/xc_agent_platform/python:3.11-slim` |
|
||
| 暴露运行端口 | `EXPOSE 8080` |
|
||
| `GET /health` 返回 200 | `main.py` 内置 HTTP 服务，`/health` → `{"status":"ok"}` |
|
||
| 环境变量 `STRATEGY_ID` | 提交任务时填入请求体 `strategyId` |
|
||
| 优雅停机（SIGTERM，30s） | 收到信号置位 `STOP`，worker 退出后关闭服务，保存状态 |
|
||
| 资源 100m/256Mi ~ 1C/512Mi | 纯标准库、单线程 worker，常驻内存 < 40MB |
|
||
|
||
另外平台会注入 `EXTERNAL_SERVICE_TOKEN`（即个人主页的 xcToken），请求头用 `Xc-Token`。
|
||
|
||
## 二、目录结构
|
||
|
||
```
|
||
.
|
||
├── Dockerfile # 镜像构建
|
||
├── main.py # 服务入口：/health、/stats + 后台提交 worker
|
||
├── cards.py # 11 张目标算力卡的 GPU 标识、默认框架、configParams 模板
|
||
├── requirements.txt # 空文件（仅用 Python 标准库，无需第三方依赖）
|
||
└── README.md
|
||
```
|
||
|
||
`cards.py` 里的 `configParams` 直接取自平台网页端选择「适配成功率最高」框架后自动生成的 YAML，
|
||
与手工在页面提交时下发的配置完全一致，避免因启动命令/端口/显存参数写错导致验证失败。
|
||
|
||
## 三、业务流程
|
||
|
||
1. `POST /api/computility/models/list/page/vo` 拉模型库（22 个种子关键词 × 最多 5 页）；
|
||
2. 过滤：仅 `文本生成`、已在 ≥`MIN_MACHINES` 张卡适配成功（说明仓库完整）、
|
||
排除 GGUF / AWQ / GPTQ / 量化（int4/int8/w8a8/w4a16/quantized/fp8/nvfp4）/ LoRA / adapter 等仓库；
|
||
3. 逐卡提交 `POST /api/adapt/task/add`，请求头 `Xc-Token`，请求体含 `strategyId`；
|
||
4. 返回码处理：
|
||
- `0` 成功，计入进度并落盘；
|
||
- `60027` 该卡已适配成功 → 跳过该组合；
|
||
- `60028` 该组合正在验证中 → 跳过该组合；
|
||
- `50000` 上游仓库拉取失败（模型已删除等）→ 跳过；
|
||
- `401/403/60014` 凭证或策略问题 → 记录错误并退避，不空转；
|
||
5. 每个模型最多提交 `QUOTA_PER_MODEL` 次（默认 2），避免同一模型刷满所有卡。
|
||
|
||
## 四、环境变量
|
||
|
||
| 变量 | 默认 | 说明 |
|
||
|---|---|---|
|
||
| `STRATEGY_ID` | 平台注入 | 策略 ID，必填 |
|
||
| `XC_TOKEN` / `EXTERNAL_SERVICE_TOKEN` | 平台注入 | xcToken，请求头 `Xc-Token` |
|
||
| `TARGET_TASKS` | 250 | 本策略要提交成功的任务数 |
|
||
| `QUOTA_PER_MODEL` | 2 | 同一模型最多提交几次 |
|
||
| `MIN_MACHINES` | 2 | 模型至少已在几张卡适配成功才入选 |
|
||
| `INTERVAL_SEC` | 1.5 | 两次提交间隔 |
|
||
| `MAX_ATTEMPTS` | 4000 | 总尝试上限，防止无限循环 |
|
||
| `MODELHUB_API_BASE` | https://www.modelhub.org.cn | 接口域名 |
|
||
| `DRY_RUN` | 空 | 置 1 时不真正提交，用于本地自测 |
|
||
| `STATE_FILE` | /tmp/modelhub_agent_state.json | 进度落盘，重启可续跑 |
|
||
|
||
## 五、本地自测（不联网提交）
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
DRY_RUN=1 STRATEGY_ID=demo TARGET_TASKS=5 python main.py
|
||
curl http://127.0.0.1:8080/health # {"status":"ok"}
|
||
curl http://127.0.0.1:8080/stats # 进度、错误码分布、最近一次事件
|
||
```
|
||
|
||
## 六、上线步骤
|
||
|
||
1. **建仓库**：在 https://dev.modelhub.org.cn 新建仓库（例如 `xc-adapt-agent`），把本目录推上去：
|
||
|
||
```bash
|
||
git init && git add . && git commit -m "feat: modelhub xc adapt agent"
|
||
git remote add origin https://dev.modelhub.org.cn/<你的用户名>/xc-adapt-agent.git
|
||
git push -u origin main
|
||
```
|
||
|
||
2. **生成 xcToken**：官网个人主页 → 设置里生成/刷新 xcToken（该 token 由平台注入到容器）。
|
||
|
||
3. **注册智能体**：官网 → 个人主页 →「我的适配智能体」→「新增智能体」，
|
||
填写名称、仓库地址、标签，提交后列表出现该智能体。
|
||
|
||
4. **运行**：在列表点「运行」启动，点「停止」中止。运行后访问 `/stats` 查看提交进度：
|
||
|
||
```json
|
||
{"submitted": [...], "attempts": 63, "codes": {"0": 20, "60028": 41}, "progress": "20/250"}
|
||
```
|
||
|
||
## 七、注意事项
|
||
|
||
- 平台对「重复/低质提交」有监控，`TARGET_TASKS` 不建议一次性设得很大，可分日多轮运行；
|
||
- 提交成功的任务仍需平台排队验证，`/stats` 只统计**提交成功**，最终是否适配成功以任务列表为准；
|
||
- 若 `/stats` 出现 `60014`，说明 `Xc-Token` 或 `strategyId` 不匹配，检查 token 是否刷新、智能体是否已上线；
|
||
- 容器被 RESTART 后 worker 会读取 `STATE_FILE` 续跑，不会重复提交已成功的组合。
|