信创模盒适配智能体（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	进度落盘，重启可续跑

五、本地自测（不联网提交）

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），把本目录推上去：

   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 查看提交进度：

   {"submitted": [...], "attempts": 63, "codes": {"0": 20, "60028": 41}, "progress": "20/250"}
   

七、注意事项

• 平台对「重复/低质提交」有监控，TARGET_TASKS 不建议一次性设得很大，可分日多轮运行；
• 提交成功的任务仍需平台排队验证，/stats 只统计提交成功，最终是否适配成功以任务列表为准；
• 若 /stats 出现 60014，说明 Xc-Token 或 strategyId 不匹配，检查 token 是否刷新、智能体是否已上线；
• 容器被 RESTART 后 worker 会读取 STATE_FILE 续跑，不会重复提交已成功的组合。