xc-model-compat-agent/README.md

xc-model-compat-agent

信创模盒的模型兼容性预检智能体。它根据用户提供的模型规模、精度、上下文长度、卡数和单卡显存，给出保守的显存预估、风险项与下一步验证建议。

安全边界

• 只分析请求中的数据，不访问外部网络。
• 不读取或输出凭据。
• 不创建、提交或修改任何模型适配任务。
• 结论属于部署前预检，不替代目标芯片上的真实运行验证。

平台约束

• Dockerfile 位于仓库根目录。
• 容器开放 8080 端口。
• GET /health 返回 HTTP 200。
• 从环境变量读取平台注入的 STRATEGY_ID，仅报告是否存在，不输出其值。
• 处理 SIGTERM，在平台 30 秒停机窗口内退出。
• 仅使用 Python 标准库，适合平台的轻量资源额度。

接口

• GET /health：存活检查。
• GET /：智能体元信息。
• POST /analyze：兼容性预检。
• POST /task：与 /analyze 相同的兼容入口。

示例：

curl -X POST http://localhost:8080/analyze \
  -H 'Content-Type: application/json' \
  -d '{
    "model_name": "example/7b-model",
    "architecture": "transformer",
    "parameters_b": 7,
    "dtype": "bf16",
    "hardware": "目标国产算力卡",
    "device_memory_gb": 24,
    "cards": 1,
    "context_length": 8192
  }'

本地验证

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