基于Clean Architecture的多模态LLM推理服务：Qwen3.5-2B的FastAPI实现

本项目是基于Clean Architecture设计原则的多模态大语言模型推理服务，通过FastAPI框架提供REST API接口，利用llama.cpp在CPU上运行量化的Qwen3.5-2B视觉语言模型。核心特色包括严格的架构分层、完整的工程实践（如请求持久化、图像存储、速率限制）及多模态推理能力，为生产环境部署多模态LLM提供高质量参考实现。

项目概述

该项目旨在构建生产就绪的多模态LLM推理服务，核心遵循Clean Architecture设计原则，确保架构纯净性与可维护性。

Clean Architecture实践

• 分层依赖规则：采用四层结构（表现层/应用层/领域层/数据层），每一层仅依赖内层，表现层用FastAPI路由与Pydantic验证，应用层含业务逻辑与DTO，领域层定义ORM实体与仓库接口，数据层处理SQLite与文件系统操作。
• 边界控制：通过依赖注入与代码审查确保分层边界清晰，端点仅依赖服务，服务依赖其他服务与仓库，避免直接导入ORM模型，实现关注点分离。

完整REST API

提供四大端点：POST /inferences（创建推理，支持multipart上传）、GET /inferences（分页查询历史）、GET /inferences/{id}（详情）、GET /inferences/{id}/image（原始图像）。

数据持久化

推理记录（提示、响应、参数等）存SQLite，上传图像存文件系统并通过UUID关联，支持审计追踪与结果回溯。

安全防护

内置速率限制（默认30次/分钟）、图像大小限制（最大10MB，最长边768像素）、MIME类型白名单（PNG/JPEG/WebP）。

采样策略

• 文本模式：Temperature=1.0（适度创造性）、Top-p=1.0（不截断）、Presence penalty=2.0（强重复惩罚）
• 视觉语言模式：Temperature=0.7（低随机性）、Top-p=0.8（适度截断）、Presence penalty=1.5（适中惩罚）

环境配置

所有设置可通过环境变量/.env覆盖，包括模型选择、上下文窗口、线程数、GPU层数等，适配开发/生产环境。

GPU加速

默认CPU运行，提供CUDA/Vulkan后端启用指南（重新安装llama-cpp-python并设置CMAKE_ARGS），通过MODEL_N_GPU_LAYERS控制GPU加载层数加速推理。

模型上下文优化

Qwen3.5-2B采用Gated DeltaNet与稀疏Gated Attention混合架构，KV缓存增长接近常数，增加MODEL_N_CTX无二次内存膨胀问题。

该项目展示了将LLM封装为生产就绪服务的全流程：从架构设计到部署配置，从错误处理到性能优化，每个细节均经过深思熟虑。对于希望在自有基础设施部署多模态LLM的团队，本项目提供了高质量参考实现，可直接复用或作为定制开发的基础。