CortexCPP 项目模型管理与 model.yaml 设计解析

模型存储架构设计

CortexCPP 采用层级分明的模型存储方案，在用户主目录下的 .cortexcpp/models 路径中构建模型仓库。该目录采用混合存储策略，既包含直接管理的 YAML 配置文件，又为每个模型分配独立子目录。

典型目录结构呈现为：

~/.cortexcpp/
└── models/
    ├── tinyllama.yaml          # 主配置文件
    ├── tinyllama/              # 模型专属目录
    │   ├── model_01.gguf       # 模型二进制文件
    │   ├── model_02.gguf       # 多分片模型文件
    │   └── model.yml           # 副本配置文件
    ├── llama3.1/               # 版本化模型目录
    └── llama3.2/               # 不同版本独立存储

双配置文件机制

项目创新性地采用双配置文件设计：

1. 全局配置文件：直接置于 models 根目录的 <model_id>.yaml 文件，作为模型管理的入口点
2. 本地副本文件：存储在各模型子目录中的 model.yml，与全局配置保持同步

这种设计既保证了模型管理的统一性，又为每个模型保留了完整的配置信息。当用户意外删除任一配置文件时，系统可通过 cortex-cpp models recover 命令进行配置重建，确保配置数据的可靠性。

模型加载与验证机制

系统通过扫描 models 目录下的 YAML 文件来识别可用模型，这种设计带来几个关键特性：

1. 完整性检查：当配置文件存在而模型二进制文件缺失时，系统会抛出 "No such file or directory" 异常
2. 版本控制：虽然当前版本号(version字段)仅用于显示，但为未来升级功能预留了扩展空间
3. 配置更新：修改 YAML 后需要重启模型服务才能使变更生效

下载与容错处理

当前版本对模型下载过程采用原子性操作设计：

• 下载中断时不会产生部分文件，而是完全回滚
• 只有下载完全成功才会生成对应的 YAML 配置文件
• 暂不支持断点续传功能，失败后需要重新下载

未来演进方向

虽然当前版本尚未实现模型更新和本地导入功能，但架构设计已为这些特性做好准备：

1. 符号链接支持：计划采用 symlink 方式实现模型导入，避免数据冗余
2. 版本升级：目录结构天然支持多版本共存，为后续升级功能奠定基础
3. 批量管理：预留了模型更新命令的扩展空间

该存储方案在简洁性和扩展性之间取得了良好平衡，既满足了当前核心功能需求，又为未来功能演进保留了充足的设计空间。