xc-model-auto-adaptation-agent/README.md

xc-model-auto-adaptation-agent

信创模盒的“模型自动适配任务智能体”。它不是只给建议的兼容性预检工具，而是一个持续运行的任务执行器。

自动执行链路

1. 启动后立即读取信创模盒公开热门模型。
2. 筛选文本生成模型，并优先选择较小的 Qwen3、Llama3 或 DeepSeek-R1-Distill 候选。
3. 用模型 ID 与国产卡枚举查询当前账号的历史验证任务。
4. 已有相同任务则记录去重结果；没有则生成 EngineX/vLLM 配置并提交验证任务。
5. 每次扫描最多提交一个任务，默认每小时重复检查。

第一版目标卡为 天数智芯｜天垓100，平台卡型枚举为 Iluvatar_bi-100，使用单卡、短上下文的保守验证配置。

平台契约

• 仓库根目录包含 Dockerfile，监听 8080。
• GET /health 始终返回 HTTP 200，并附带扫描器最近状态。
• 从平台注入的 STRATEGY_ID 获取自身策略 ID。
• 优先读取 MODELHUB_XC_TOKEN，同时兼容官方参考策略使用的 EXTERNAL_SERVICE_TOKEN。
• 正确处理 SIGTERM，在平台 30 秒窗口内退出。
• 仅使用 Python 标准库，符合 1 CPU / 512 MiB 的平台限制。

安全边界

• 令牌只从运行环境读取，不写入仓库、响应或日志。
• stdout 只记录令牌是否存在，不记录令牌值、请求头或完整 API 响应。
• 提交前必须完成精确去重；API 返回非成功业务码时不会伪报成功。
• 未获得令牌或策略 ID 时会明确记录 task_submission_blocked，不会静默假运行。

端点与关键日志

• GET /health：服务与扫描器状态。
• GET /scanner：最近候选、动作和错误类型。
• POST /analyze：返回该模型的实际适配执行计划。

正常启动后的关键事件依次为：

service_started
scanner_started
candidate_scan_started
candidate_discovered
task_duplicate_skipped 或 task_submitted

如果运行环境配置不完整，会看到 task_submission_blocked 和具体缺失项。

本地验证

python3 -m unittest -v
python3 main.py
curl http://localhost:8080/health