# 基于Clean Architecture的多模态LLM推理服务：Qwen3.5-2B的FastAPI实现 > 采用Clean Architecture架构，通过FastAPI和llama.cpp在CPU上提供多模态Qwen3.5-2B视觉语言模型推理服务，支持SQLite持久化和完整的REST API。 - 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm) - 发布时间: 2026-04-28T12:13:37.000Z - 最近活动: 2026-04-28T12:27:28.239Z - 热度: 132.8 - 关键词: FastAPI, Clean Architecture, Qwen3.5, 多模态, llama.cpp, GGUF, 视觉语言模型, REST API - 页面链接: https://www.zingnex.cn/forum/thread/clean-architecturellm-qwen3-5-2bfastapi - Canonical: https://www.zingnex.cn/forum/thread/clean-architecturellm-qwen3-5-2bfastapi - Markdown 来源: ingested_event --- ## 项目概述与架构理念 该项目是一个基于Clean Architecture设计原则的多模态大语言模型推理服务。它通过FastAPI框架提供REST API接口，利用llama.cpp在CPU上运行量化的Qwen3.5-2B视觉语言模型。项目的核心特色在于其严格的架构分层和完整的工程实践，包括请求持久化、图像存储、速率限制等企业级特性。 ## Clean Architecture的严格实践 项目对Clean Architecture的实现堪称教科书级别，通过代码层面的强制约束确保架构的纯净性： ### 分层依赖规则 架构采用经典的四层结构，每一层只依赖于内层： - **表现层（Presentation）**：FastAPI路由处理HTTP请求，使用Pydantic进行请求/响应验证 - **应用层（Application）**：包含业务逻辑服务和数据传输对象（DTO） - **领域层（Domain）**：定义SQLAlchemy ORM实体和仓库接口 - **数据层（Data）**：SQLite数据库和文件系统操作 ### 严格的边界控制 项目通过代码审查和架构规则确保分层边界的清晰：端点仅依赖于服务（通过依赖注入），服务依赖于其他服务和仓库，端点绝不直接导入仓库或ORM模型。这种设计使得各层可以使用最适合的数据结构：端点使用Pydantic模型，服务使用dataclass，仓库使用ORM模型，实现了关注点分离。 ## 技术栈与核心特性 ### FastAPI与异步支持 项目基于FastAPI构建，充分利用Python的异步特性。模型作为进程级单例由FastAPI生命周期管理，所有阻塞的llama.cpp调用都在工作线程中执行，确保事件循环保持响应。这种设计在处理模型加载和推理等耗时操作时尤为重要。 ### llama.cpp与GGUF量化 项目使用llama.cpp运行GGUF格式的量化模型，默认配置使用bartowski/Qwen_Qwen3.5-2B-GGUF的Q4_K_M量化版本（约1.33GB）和对应的视觉投影器（约0.67GB）。首次启动时自动从Hugging Face下载模型，后续启动复用缓存，CPU加载通常在10秒内完成。 ### 多模态推理能力 服务支持文本和图像两种输入模式。当请求包含图像时，系统使用视觉语言（VL）采样配置；纯文本请求则使用文本采样配置。这种区分对于Qwen3.5-2B模型尤为重要，因为官方模型卡指出该模型在贪心解码下容易产生重复或思考循环。 ## 企业级功能实现 ### 完整的REST API 项目提供了完善的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运行，但项目提供了详细的GPU加速指南。通过重新安装llama-cpp-python并设置CMAKE_ARGS，可以启用CUDA或Vulkan后端。配置MODEL_N_GPU_LAYERS参数可以控制加载到GPU的层数，在资源允许的情况下显著加速推理。 ### 模型上下文优化 Qwen3.5-2B采用了Gated DeltaNet和稀疏Gated Attention的混合架构，使得KV缓存增长接近常数级别，与上下文长度无关。这意味着可以增加MODEL_N_CTX而不会遇到传统Transformer模型的二次内存膨胀问题。 ## 工程实践价值 该项目展示了如何将一个大语言模型封装为生产就绪的服务。从架构设计到部署配置，从错误处理到性能优化，每个细节都经过深思熟虑。对于希望在自己的基础设施上部署多模态LLM的团队，该项目提供了一个高质量的参考实现。