xc-tianga100-advisor-agent/README.md

xc-tianga100-advisor-agent

信创模盒的 天数智芯｜天垓100 专属部署前预检智能体。

能做什么

• 后台定时读取信创模盒公开热门模型，自动发现文本生成候选模型。
• 选择较小且与官方 EngineX 支持家族相符的候选，按模型与卡型查询历史任务去重。
• 当运行环境同时提供私密令牌、策略 ID、合法卡型枚举与验证配置时，自动提交一条验证任务。
• 校验用户指定的目标卡是否与本智能体的官方卡型一致。
• 收集模型、框架、后端、驱动和 SDK 版本，明确缺失信息。
• 根据多卡、量化、长上下文、自定义算子和动态形状提示验证风险。
• 给出从设备可见性到模型最小输入的验证顺序。

事实边界

• 卡型名称来自信创模盒“模型 X 算力”页面。
• 不声明页面未提供的显存、算力、SDK 版本或算子支持结论。
• 只访问信创模盒公开候选接口和官方任务接口；不执行系统命令。
• 无私密 MODELHUB_XC_TOKEN 时只扫描、记录候选，不创建任务。
• 令牌只从运行环境读取，不写入仓库、HTTP 响应或 stdout。
• 最终兼容性必须以目标设备上的真实日志和测试结果为准。

自动工作模式

• AUTO_SCAN_ENABLED：默认 true，启动后立即扫描，之后每小时扫描一次。
• SCAN_INTERVAL_SECONDS：扫描间隔，最小 60 秒，默认 3600 秒。
• AUTO_SUBMIT_ENABLED：默认 true；缺少任一必要配置时自动降级为只读扫描。
• MODELHUB_XC_TOKEN：调用任务查询/创建接口的私密 Xc-Token，不得写进公开代码。
• MODELHUB_TARGET_GPU：平台内部卡型枚举。只有已由官方任务记录核验的枚举才可配置。
• MODELHUB_CONFIG_PARAMS：验证任务 YAML；未内置官方配置的卡型必须通过私密部署配置提供。
• 每次扫描最多提交一个候选；提交前用 modelId + gpuType 精确查询历史，已有任务则跳过。

日志

• stdout 使用单行 JSON，记录服务启动、扫描、候选、去重、提交结果、健康检查、分析结论和优雅停机。
• 仅记录经过清洗的模型标识、结论和必要状态，不输出整个请求体、凭据、URL 查询参数或环境变量值。

平台约束

• 仓库根目录包含 Dockerfile，容器开放 8080。
• GET /health 返回 HTTP 200。
• 读取 STRATEGY_ID，仅报告是否存在，不输出其值。
• 处理 SIGTERM，在平台 30 秒窗口内退出。
• 仅使用 Python 标准库。

接口

• GET /health：存活检查。
• GET /：卡型和智能体元信息。
• GET /scanner：后台扫描器最近状态，不包含令牌或策略 ID。
• POST /analyze：部署前预检。
• POST /task：与 /analyze 相同的兼容入口。

示例：

curl -X POST http://localhost:8080/analyze \
  -H 'Content-Type: application/json' \
  -d '{
    "model_name": "example/model",
    "hardware": "天数智芯 天垓100",
    "framework": "PyTorch",
    "backend": "目标后端",
    "sdk_version": "实际版本",
    "driver_version": "实际版本",
    "precision": "bf16",
    "cards": 1
  }'

本地验证

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