Repository navigation
mineru-llama-cpp 0.2.1 完善引擎故障状态和异步取消行为,并优化多平台 wheel 构建流程。
引擎生命周期与错误处理
- 新增
Engine.check_health(),无需提交推理即可查询原生解码循环是否已经退出。该接口用于检查存活状态,不会把暂时无输出或正在执行的调用判定为故障。 - 新增
EngineUnavailableError和EngineClosedError,分别表示引擎循环已确认退出、调用方已显式关闭实例。终止后的实例拒绝后续推理;普通请求错误仍与引擎永久不可用状态区分。 - 保留结构化错误的
error_type、code和details。原生循环可捕获的异常会记录首次 C++ 异常类型与消息,并让等待读取结果的请求在后续轮询中退出。 - 取消
agenerate()时,尚未开始的排队任务会跳过推理,已提交的原生调用会等待执行结束再返回。异步流显式关闭或取消时也会等待工作线程结束,避免调用方过早释放仍被使用的引擎。 - 取消清理期间发现的引擎终止错误会保留,便于上层批量任务统一处理故障。
构建与分发
- PR 构建前先运行工作流、平台策略和 SDK 缓存检查;普通
main推送仅运行快速检查,版本标签运行完整矩阵,减少发布提交与标签触发的重复构建。 - 缓存 cibuildwheel 下载和 C/C++ 编译结果,按操作系统、架构和工具链隔离;Linux 在缓存命中时先验证 Vulkan SDK,减少不必要的依赖安装。
- 精简构建目标至 Python 扩展和
llama-server,所依赖的运行库与 CPU/GPU 动态后端继续随 wheel 分发。
兼容性
- Python 3.11+,五个平台提供
cp311-abi3wheel,安装测试覆盖标准 GIL 版 CPython 3.11–3.14。 - Linux x86_64/aarch64、Windows AMD64/ARM64 使用 CPU/Vulkan;macOS arm64 使用 CPU/Metal,最低 macOS 14。
- llama.cpp 继续固定为
86a283532072722c5f3363d37d59a874d09fa99b。 - 关闭引擎前仍需等待调用结束。进程级崩溃、
abort和访问冲突需要由进程管理层处理;本版本不声明修复所有原生崩溃原因。
安装:
python -m pip install --upgrade mineru-llama-cpp==0.2.1发布验证
- 正式构建 CI:五个平台、Xcode 16.4 兼容性检查、平台汇总及严格稳定 ABI 审计全部通过。
- PyPI 发布流程:构建产物验证、发布准备和上传全部成功;PyPI 0.2.1 的五个 wheel 哈希与本页附件及
SHA256SUMS一致。 - 本地发布前策略与原生状态检查共 142 项通过。正式 macOS wheel 在独立 Python 3.11 环境中完成 CPU/Metal 后端加载及 21 项生命周期、异步取消、真实模型回归,全部通过。
- 另从 PyPI 下载并校验 macOS wheel,重新安装后通过真实模型短文本推理、推理前后
check_health()和关闭后EngineClosedError检查。