这份《AI开源模型实践指南》在社区开源之后，我收到的私信比过去一年加起来的都多。大家问得最多的不是某个模型效果怎么样，而是同一个问题：资料那么多，我到底该从哪学起？说实话，这恰恰是我们做这份指南的初衷。过去一年多，AI开源模型的迭代速度已经快到让人焦虑——今天出一个新模型，明天出一个新框架，后天又有人告诉你“再不学Prompt Engineering就晚了”。但真正动手做过项目的人都知道，90%的教程都在讲“术”，很少有人把“道”讲清楚：模型怎么选、部署怎么做、成本怎么控、应用怎么接、踩坑怎么排查。
这份指南就是我们团队把过去一年踩过的坑、调过的参、重构过的代码，全部整理成的一份可以直接照着做的实操手册。它不是什么学术论文，也不是什么趋势分析，就是一群写代码的人，把从零搭建一套AI应用的全过程，用最朴素的方式记录了下来。今天这篇文章，我会把指南里最核心的几个模块拆开来讲，包括模型选型、本地部署、AI编程与Agent开发、工程化落地，以及我们在实际项目中遇到的典型问题和排查思路，希望能帮你省掉那些我们曾经白白浪费的时间。
1. 这份指南为什么值得看：从“模型选择困难症”说起
先说一个我在社群里的真实观察。很多新手入坑AI应用开发，第一步就卡住了——模型实在太多了。Qwen、Llama、DeepSeek、GLM、Mistral、Yi，每个都有不同参数规模，还有Base版和Chat版之分，再加上量化和微调这些概念，整个人都是懵的。好不容易选了一个模型，又倒在了部署这一步，不是显存不够，就是依赖装不上，或者跑起来了但速度慢得离谱。
1.1 新手最容易陷进去的三个误区
第一个误区是盲目追求大参数。很多人一上来就想本地跑一个70B的模型，觉得参数越大越聪明。但实际项目里，你的业务场景可能只需要一个7B甚至3B的模型就能解决80%的问题，而且推理速度快好几倍，部署成本低一个数量级。
第二个误区是混淆了Base模型和Chat模型。Base模型是“半成品”，只学会了语言规律，但没学会对话。如果你直接拿Base模型去接业务，得到的输出几乎不可用。它需要经过监督微调（SFT）和人类反馈对齐（RLHF）才是我们日常使用的对话模型。
第三个误区是忽略模型的中文能力和工具调用能力。有些英文模型在国际榜单上评分很高，但拿到中文业务场景里，生成的内容就是有一股“翻译腔”，而且对中文指令的理解经常跑偏。更关键的是，如果你要做Agent应用，模型必须支持Function Calling或者Tool Calling，这一条就直接筛掉了一批早期模型。
1.2 指南的定位与目录设计
我们这份指南在设计之初就确定了三个原则：第一，不写纯理论，每个章节都必须能落地；第二，不搞排行榜，因为模型更新太快，今天的第一名下个月可能就被超越了；第三，不回避坑，把实际项目中遇到的所有问题都如实记录。
所以指南的目录是围绕一条完整的项目开发链路来设计的，从环境准备、模型选型、本地部署、API服务封装，到Prompt编写、RAG检索增强、微调实战，最后是性能优化与项目部署。你可以把它当成一份“AI应用开发的地图”，从头到尾走一遍，或者当成字典，遇到具体问题查阅对应章节。
1.3 一条可复制的AI学习路线
如果你是非科班出身，或者刚转行来做AI应用开发，我建议你按这个顺序来学习，这也是指南里推荐的路线。第一阶段是“会用”：先学会用现成的工具和平台调用大模型API，理解Prompt的基本语法和设计技巧，能做出一个聊天机器人或者文档问答工具。第二阶段是“会改”：学会用开源模型做本地部署，理解模型推理的基本原理，通过调整参数、切换量化方式、优化Prompt来改善效果。第三阶段是“会造”：掌握RAG、Function Calling、Agent框架这些进阶技术，能够根据业务需求组合不同的模型和工具，构建复杂的应用系统。
这条路线最关键的一点是，每个阶段都有对应的实践项目和验收标准。比如第一阶段结束时，你应该能独立完成一个调用API的对话应用，并能解释清楚Temperature和Top-P这两个参数对生成结果的影响。有了这样的明确目标，学习就不会变成漫无目的地刷教程。
2. 模型选型与本地部署：先把地基打牢
模型选型这件事，说难很难，说简单也简单。难是因为模型矩阵太复杂，简单是因为只要抓住了你的业务场景、部署环境、成本预算这三个约束条件，答案基本就浮出水面了。我在指南里用一个章节专门讲模型分类和选型逻辑，这里把最核心的框架分享出来。
2.1 主流开源模型分类与适用场景
我把当前常见的开源模型分成五类。第一类是通用对话模型，代表有Qwen系列、Llama系列、DeepSeek、GLM、Yi等，适合做客服、聊天、内容生成等通用场景。第二类是代码模型，代表有DeepSeek-Coder、Qwen-Coder、CodeLlama等，适合做代码生成、代码补全、代码解释。第三类是多模态模型，代表有Qwen-VL、InternVL、LLaVA等，支持图像输入，能做图片理解、OCR、图表分析。第四类是向量模型，代表有BGE、GTE等，它们不负责生成文字，而是把文本转成向量，主要用做RAG系统中的检索模型。第五类是语音模型，代表有Whisper和FunASR，负责语音转文字或者文字转语音。
每类模型我建议重点关注2-3个代表即可，不用全部追踪。比如通用对话模型，我长期关注Qwen系列和DeepSeek，因为这两个在中文场景表现稳定，社区生态活跃，遇到问题很容易搜到解决方案。
2.2 本地部署的硬件配置与量化方案
很多人一听到“本地部署”就以为需要好几张A100，其实完全不必。关键在于你用什么量化和什么推理框架。量化简单理解就是把模型的精度从FP16（16位浮点数）降到INT8或者INT4，代价是损失一点点精度，收益是显存占用大幅下降、推理速度提升。
以7B参数模型为例，FP16精度下显存占用大约是14GB，INT8量化后降到大约7GB，INT4量化后只需要大约4-5GB。这意味着什么？一张消费级的RTX 4060（8GB显存）就能流畅运行7B模型的INT4量化版本。如果是13B模型，INT4量化后大约需要8-10GB，RTX 4070 Ti Super级别或者12GB显存的显卡就能扛住。70B模型INT4量化后大约需要40GB显存，就需要两张24GB显卡或者一张48GB的专业卡了。显存估算有一个粗略公式：模型显存占用约等于参数数量（B）乘以每个参数的字节数。FP16是2字节，INT8是1字节，INT4是0.5字节，然后再加上KV Cache的开销。
2.3 部署工具选型：Ollama、vLLM与llama.cpp
部署工具的选择同样重要，不同工具适合不同场景。如果你只是想本地快速体验或者做开发调试，Ollama是最省事的选择，一行命令就能拉起一个模型服务，还自带OpenAI兼容的API接口，但它更适合低并发场景，高并发下的吞吐量不如专业推理引擎。如果你要做生产环境的API服务，vLLM是当前社区的主流选择，它通过PagedAttention等技术大幅提升了推理吞吐量，支持Continuous Batching（连续批处理），在并发请求较高时有明显优势。如果你的硬件比较特殊，比如只有CPU环境或者要在树莓派这样的边缘设备上跑，llama.cpp是更好的选择，它对CPU推理做了深度优化。
还有一个容易被忽略的点是模型的格式兼容性。Ollama和llama.cpp主要使用GGUF格式，vLLM通常使用Hugging Face原生的safetensors格式，也可以直接加载AWQ或GPTQ量化模型。格式不对是会直接加载报错的，这个细节在部署实战中非常关键。
2.4 显存估算与运行参数调优
我把显存估算和参数调优放在一起写，因为它们在实操中是联动的。显存占用不仅包括模型权重，还包括KV Cache和计算过程中的激活值。KV Cache是推理过程中缓存注意力机制中间结果的空间，它和输入输出长度成正比，所以当你遇到“显存够但跑长文本就OOM”的时候，大概率就是KV Cache在爆炸。解决方案是限制最大生成长度，或者用支持GQA（分组查询注意力）的模型，GQA能大幅压缩KV Cache的占用。
运行参数里，最常调的几个是max_length、temperature、top_p和top_k。max_length就是生成的最大长度，影响显存和时间，够用就好。temperature控制随机性，值越大输出越发散，值越小越发确定。top_p是核采样，表示只从累计概率达到p的候选词里采样。做代码生成或者逻辑推理任务，我通常把temperature设成0.2左右；做创意写作，可以调到0.7到0.9之间。
注意：不要同时把temperature和top_p都调得很大，否则输出会非常不稳定。实际操作中，固定其中一个，只调另一个，效果更可控。
3. 从“会聊”到“会做”：AI编程与Agent开发实战
模型部署好了，API也能调通了，接下来就到了真正有意思的阶段——让模型帮我们干活。这个阶段的核心是两件事：一是把模型接入到编程工具链里，让AI成为开发的加速器；二是理解Agent的工作原理，让模型能够自主调用工具去完成复杂任务。
3.1 开源模型如何接入AI编程工作流
最近AI编程的话题很热，像Claude Code这类工具确实把编程门槛拉到了一个新高度。但要注意，Claude Code自身并不是开源模型，如果你受限于数据安全要求，只能用开源模型做AI编程，也有成熟的方案。
目前最常用的路线是Continue和Cline这两个VS Code插件。它们支持配置多种模型后端，包括本地部署的开源模型。也就是说，你可以把本地部署的Qwen-Coder通过Ollama或者vLLM暴露成OpenAI兼容的API，然后在Continue插件里填上这个API地址，就能在IDE里获得代码补全、代码解释、代码重构的能力。实测下来，对于Python和Java这类主流语言的常见任务，7B-14B的代码模型表现得很不错，虽然和顶级商用模型还有差距，但胜在数据不出内网、不花额外API费用。
3.2 AI Agent的结构拆解与提示词设计
做Agent是当前AI应用开发最火的方向之一，但很多初学者把Agent理解成“调用大模型聊天”，这是不对的。一个真正可用的Agent至少包含四个部分：模型推理、工具调用、记忆管理、任务规划。模型推理就是大模型本身，负责理解和决策；工具调用是让模型能调用外部API或函数，关键依赖模型的Function Calling能力；记忆管理是让Agent能记住对话历史和中间结果；任务规划是让Agent把一个大目标拆解成多个小步骤并逐步执行。
提示词设计在Agent开发里尤其重要。我给Agent写系统提示词时，一定会包含四块内容：角色定义（你是谁）、任务描述（要完成什么）、约束条件（不能做什么、必须怎么做）、输出格式（结构化输出要求）。四块缺一不可，缺少约束条件会让Agent天马行空，缺少输出格式会让下游程序无法解析结果。
3.3 多模态与创意应用的扩展
除了文本生成，开源模型在创意领域的应用也非常广泛。写小说、生成短剧剧本、辅助画画、生成视频，这些场景现在都有对应的开源模型方案。文本创作可以直接用通用大模型配合精心设计的Prompt，目前很多短剧编剧已经在用这套流程做剧本初稿。图像生成可以关注Stable Diffusion生态和Flux，通过LoRA模型可以训练特定风格或者特定角色。视频生成是下一波热点，开源方案的成熟度不如图像生成，但已经有一些值得关注的项目在快速迭代。
做创意类应用和做工具类应用有一个显著区别：前者更看重生成结果的“惊喜感”，所以Temperature可以调高一些，Prompt要给模型留出发挥空间；后者更看重稳定性和准确性，所以Prompt必须精确，参数要保守。这个差异在提示词设计时就要考虑进去。
3.4 一个Agent小项目的完整实现过程
我结合指南里的案例，分享一个最简单的Agent实现流程。假设我们要做一个“股票查询助手”，用户问“帮我查一下某只股票的当前价格和历史趋势”，大模型本身并不知道实时股价，它需要通过工具调用去获取。
第一步，定义一个查询股价的工具函数，比如get_stock_price(stock_code)，这个函数内部去调用某个行情API。第二步，在调用模型时，把工具函数的描述以JSON Schema的形式传给模型，告诉模型“你有一个工具可以用，当用户问你股价时，你生成一个调用这个工具的动作”。第三步，模型返回的内容里是一个结构化的函数调用指令，而不是直接回答，我们在代码里解析这个指令，执行对应的函数，拿到真实股价数据。第四步，把股价数据作为上下文再传给模型，让模型根据这个真实数据组织语言回答用户。
整个流程看起来简单，但每一步都有坑。比如工具描述的JSON Schema写得不清楚，模型就会反复调用错误的参数；再比如没有处理模型返回多个函数调用的情况，程序就直接崩了。这些细节在指南里都有对应的代码示例和错误案例。
4. 工程化落地：API服务、RAG与微调
模型能在本地跑通、能写小脚本调用，这只是万里长征走完了第一步。真正的挑战在于把它变成一个稳定、高效、可维护的产品服务，这也就是我常说的“能演示的Demo和能上线的系统之间差着一整个工程化”。
4.1 模型API化与Spring AI等框架集成
大模型部署完成后，通常是通vLLM或Ollama暴露一个HTTP API，这个API一般兼容OpenAI的接口格式。这样做的好处是你的应用层代码不需要绑定特定模型，今天用Qwen，明天换DeepSeek，只要API地址换一下就行。当然也有Ollama那种更简单的做法，部署后自带REST API，局域网内其他服务可以直接调用。
之前有朋友问我，Spring AI这类框架在项目里到底起了什么作用？简单来说，它给Java开发者提供了一层标准化的接口，把和大模型交互的细节打包好了。你可以不用自己拼HTTP请求、不用自己解析SSE流式响应，直接用Spring AI提供的ChatClient或者ChatModel接口，像调用普通Java方法一样调用大模型。对于团队里全是Java工程师、没有太多Python背景的情况，这是把AI能力集成进现有微服务体系的便捷路�径。在Spring AI里配置模型地址，本质是设置base-url和api-key，非常类似配置一个数据库连接池。
4.2 RAG落地细节：从文档处理到检索效果调优
RAG（检索增强生成）是当前让大模型“学会私有知识”最主流、最经济的方案。它的核心思路很简单：用户提问时，先从你的知识库里检索出相关文档片段，把这段内容作为上下文塞给大模型，让大模型基于这些内容作答。很多新手以为RAG就是把文档扔给向量数据库就行，实际落地时细节非常多。
文档切片是第一个关键环节。切片太大，检索出来的内容包含太多不相关信息，大模型的回答会被带偏；切片太小，单个片段可能没头没尾，信息不完整。我常用的策略是先用标题结构切分大章节，再按固定长度（比如400-600个字符）切分，并设置相邻切片10%-15%的重叠，避免关键句被拦腰截断。
嵌入模型的选择也很关键。检索效果的上限由两个因素决定：一是嵌入模型能不能正确理解你的文档语义，二是检索策略能不能召回正确的内容。在中文场景里，BGE系列和GTE系列的向量模型表现稳定，比直接用通用大模型的嵌入效果更可靠。如果预算允许，建议在向量检索后再加一个Reranker（重排序模型），它能对召回的前几十条结果做精确的语义排序，把最相关的内容排在前面，效果立竿见影。
有一句话我很认同，“RAG的效果上限由检索引擎决定，下限由大模型决定”。检索不到相关内容，大模型再强也是巧妇难为无米之炊。
4.3 微调该不该做，什么场景才值得
很多老板上来就要微调开源模型，理由是我们有行业数据。但微调不是万能药，甚至是很贵的一味药。我见过不少团队花了大半个月做微调，效果却不如好好设计Prompt加一套RAG。微调真正的适用场景是这三类：第一，需要模型输出特定格式，比如必须严格输出JSON且字段名固定；第二，需要模型掌握特定领域的术语和表达风格，比如法律文书、医疗报告的书写规范；第三，需要模拟某个角色的语气，比如让模型模仿某位作家的风格写文案。
如果是想让模型学习知识，比如把公司产品文档塞进模型脑子里，这就用错了方式。模型微调很难可靠地注入事实性知识，它只会“背”个大概，细节经常出错，而且还可能把原有能力搞坏。知识类需求应该走RAG，微调只负责调整“说话方式”。
如果确定要微调，我建议从LoRA或QLoRA这类参数高效微调方案入手，它们只训练一小部分参数，成本低、速度快，效果在很多场景下已经够用。全参数微调对硬件和数据的门槛高很多，除非没有后路，否则一开始不建议碰。
4.4 性能优化与成本控制
上线之后，性能和成本就是头等大事。我先说性能。影响用户体验的核心指标有两个：首Token延迟（TTFT）和非首个Token生成速率。首Token延迟就是用户发出请求到收到第一个字符的时间，它主要受模型推理的PreFill阶段影响，和输入长度、提示词复杂度有关。生成速率是首Token之后每个Token生成的速度，它和模型大小、量化方式、硬件性能、并发数都有关系。
首Token延迟优化最直接的手段是精简提示词，把不需要的系统提示和示例删掉。因为PreFill阶段要对整个输入进行完整计算，输入越长，首Token延迟越高，成本也越高。生成速率优化则更多依赖推理框架和硬件，比如用vLLM代替简单的API包装，开启Continuous Batching，把并发请求合并成批次处理，能显著提升吞吐量。
成本控制上，用量化模型配上合适的部署架构是最有效的手段。7B模型的INT4量化版本在综合能力上能超越早期一些13B甚至30B模型的表现，但所需显存和每小时运行费用却低得多。尽量让业务需求去匹配模型规模，而不是一味追求“大而全”。另外，别忘了规划缓存策略，对于相同或相似的用户问题，结果可以直接缓存，避免重复调用大模型。
注意：模型推理服务的失败率和延迟监控一定要做。即使模型输出质量再好，如果服务稳定性不达标，用户同样会选择离开。
5. 常见问题与排查技巧实录
指南发布之后，我在GitHub Issues里收到了大量反馈，大家遇到的问题高度集中。我把这些问题整理成了速查表，这里也分享给读者，希望能帮你少走弯路。
5.1 部署环节高频报错速查
部署模型时最常遇到的问题有五个。第一个是CUDA out of memory，也就是显存不足，解决办法是切换更大量的量化模型，或者关闭一些不需要的环境，比如浏览器、IDE等占显存的程序，同时降低max_length。第二个是依赖版本冲突，典型的是PyTorch版本需要CUDA版本和显卡驱动不匹配，环境里装了很多AI相关框架后冲突尤其明显。第三个是模型文件下载太慢或者下载失败，因为模型文件动辄几个G到几十个G，建议用专业的下载工具或者设置镜像源。第四个是API请求报401，说明API Key没设置对，或者框架与本地服务之间的鉴权配置不匹配。第五个是输入返回异常，比如模型回复乱码，一般是编码问题，统一使用UTF-8即可。
5.2 为什么生成效果总是不稳定
很多人发现同一个模型、同一个提示词，每次生成的结果都不一样。这个现象在多数情况下不是bug，而是参数设置的必然结果。Temperature、Top-P、Top-K这些都控制着采样过程的随机性，它们不为0的时候，模型每次生成的路径都可能不同。如果你需要稳定的结果，有几个办法：一是把Temperature设为0或接近0，这时大多数推理引擎会采用贪心解码，每次基本输出相同的答案；二是固定随机种子，但这只能在部分推理框架里生效；三是设计更详细、更结构化的提示词，缩小模型的选择空间。
如果效果不稳定表现为同一个需求有时回答得很专业、有时胡说八道，那问题大概率出在上下文管理上。你的系统提示词是否稳定？历史消息是否引入了噪声？检索出来给模型的上下文到底匹配不匹配？这些都比调采样参数的影响大得多。
5.3 关于Prompt设计，我一直在用的几个原则
Prompt设计是性价比最高的调优手段，没有之一。但Prompt设计没有银弹，需要针对场景反复迭代。我总结了几条比较通用的原则。
第一是“先给限制，再给自由”。在系统提示词的开头就写明不能做什么，比如“你不是法律顾问，不能提供法律意见”“不要输出与问题无关的内容”，这比你在结尾反复强调更有效。第二是“给示例比给描述强”。想让模型按特定格式输出，与其用文字描述格式，不如直接给它一个输入输出的示例，它能更快地模仿。OpenAI提出的“Few-shot”就是这个原理。第三是“把关键信息放在开头和结尾”，大模型在长文本里对中间内容的注意力会衰减。第四是“输出长度要说请楚”，比如要求“200字以内”或者“最多5条”，不限定的话模型经常会给出一大段。
只要你动手做过几个真实项目，就会发现Prompt设计的功力完全建立在你对模型的观察之上，而不是背了多少模板。
5.4 从指南使用者反馈中总结的几条实用心得
最后从用户反馈里说说我印象最深的几句。有开发者反馈，本地部署最大的门槛不是技术，而是他一开始就掉进了“版本地狱”，反复折腾依赖后差点放弃，后来直接用我们推荐的Docker镜像，十五分钟就跑通了。有测试工程师提到，让大模型辅助写测试用例，用开源的7B代码模型配合精心设计的Prompt就能覆盖大部分场景，明显提高了迭代效率。另一个做知识库问答的团队说，他们在接入Reranker后，检索准确率从60%出头直接提升到了85%以上，而且只增加了不到50毫秒的延迟。
这些事情让我意识到，技术很多时候不是越新越好，也不是越大越好。一套清晰的选择标准、一份详细的避坑清单，往往比追着新模型跑更有价值。
我个人在实际操作中最大的体会是，不要把开源模型当成“免费的午餐”去到处套用，而是要当成一个可以深度定制的技术底座，想清楚你的业务约束在哪里，你的数据边界在哪里，你的成本红线在哪里。想清楚这三件事，你基本就不会被铺天盖地的信息淹没，也能找到最合适的那条实现路径。
