1.1 教程目标、适用人群与学习成果
我自己刚接触AI模型那会儿，网上翻了一大堆资料，东一榔头西一棒子，学得特别零散。有的文章只讲API调用，有的视频光说本地部署，还有的博客一上来就丢一堆参数，看得我头大。这个教程就是想把散落的知识串成一条线，从选模型到真正把应用跑起来，中间每一步都给你说明白。我的目标很直接：你跟着走一遍，能独立完成模型调用、能判断什么场景该用云端什么场景该上本地、还能自己排查常见问题。
这套内容适合哪些人呢？如果你是会写一点代码的开发者，想快速把大模型能力接进自己的项目，那正好。产品经理和创业者也可以看，前几章能帮你搞清楚技术边界和成本结构，跟团队沟通的时候心里有底。我还特意考虑到了刚入门的朋友，前置知识那节会把需要补的课列清楚，你不会因为看不懂某个术语就卡住。有经验的工程师可以直接跳到感兴趣的章节，每章相对独立，不影响理解。
学完之后你能拿到什么？我列几条实在的。你能独立完成一次完整的API调用，知道怎么传参、怎么解析返回结果、出错怎么处理。你能在自己的电脑或者服务器上把开源模型跑起来，理解量化是怎么回事、显存怎么算。你还会有能力做技术选型，面对一个具体需求，能判断用哪个模型、走哪条路更划算。这些成果不是纸上谈兵，每一条都对应着教程里的实操环节。
1.2 AI模型使用方式全景：云端API、本地部署与托管平台
我习惯把AI模型的使用方式分成三条路，每条路都有它舒服的地方和不舒服的地方。云端API最省心，你注册个账号拿到密钥，几行代码就能调通。模型的训练、推理、扩缩容全由服务商管着，你只管用。缺点也明显，数据要出你的服务器，按token计费，用得多成本就上去了。我刚开始做小项目的时候特别喜欢这种方式，快速验证想法，不用操心硬件。
本地部署是另一条路。模型权重下载到自己机器上，推理框架装好，服务起在本地的端口。数据不出内网，调用不要钱，想怎么改就怎么改。这条路对硬件有要求，显存不够大模型跑不动，量化能缓解一些但效果会打折扣。我自己的经验是，涉及到敏感数据或者需要深度定制的场景，本地部署更踏实。调试的时候也方便，日志、中间结果都能看到。
托管平台算是中间路线。你把模型部署到云厂商的推理服务上，底层资源他们管，模型选择和环境配置你自己来。弹性扩缩容比纯本地省心，数据隔离比纯API好一些。我在做中等规模应用的时候倾向这种方式，既不用自己维护机器，又能对模型有更多控制权。三条路没有绝对的好坏，关键看你的数据敏感度、预算和团队的技术储备。
1.3 从模型选择到应用落地的完整学习路径
学习路径这件事我琢磨了很久，怎么排顺序才不让人半路放弃。我的建议是先跑通再深挖。你先把一个最小的调用示例跑起来，看到模型返回结果，这个正反馈特别重要。很多人一上来就啃理论，参数、注意力机制、微调方法，啃了两周还没调通一个接口，热情就磨没了。先动手，遇到问题再回头补理论，效率高得多。
跑通之后往外扩。学会处理流式输出，让界面有打字机效果。学会多轮对话，维护好消息历史。学会函数调用，让模型能触发你定义好的工具。这几个能力是大多数应用的骨架，掌握之后你就能做出像样的东西了。我当初卡在流式输出好久，后来发现就是处理一下数据块的拼接，没那么玄乎。
再往后是工程化的事。错误重试、限流应对、成本监控、日志记录，这些不炫酷但决定你的应用能不能稳定跑。最后才是优化，提示词怎么调、输出质量怎么控、延迟和成本怎么平衡。这个顺序不是死的，你可以根据手头的项目灵活调整。我写这个教程的时候尽量让每章都能单独看，你缺哪块补哪块。
1.4 前置知识、工具链与资源清单
前置知识我说得直白一点。你得会一门编程语言，Python最合适，生态最全，示例最多。JavaScript也行，很多API有现成的SDK。命令行操作要熟悉，装包、跑脚本、看日志这些躲不掉。HTTP请求的基本概念得懂，GET和POST的区别、请求头响应头是干嘛的，这些不了解的话调API会很痛苦。数学基础不用太深，知道向量、矩阵大概是什么就行，不影响你使用模型。
工具链我列一下自己常用的。代码编辑器用VS Code，插件生态好，调试方便。Python环境管理用conda或者uv，依赖冲突能少很多。接口调试用Postman或者curl，排查问题的时候比在代码里打日志快。版本控制用git，这个不用多说。本地部署的话看你的硬件，NVIDIA显卡用CUDA，Mac用Metal，推理框架选Ollama或者vLLM，前者上手快后者性能好。
资源清单我挑几个真正有用的。官方文档永远排第一，OpenAI、Anthropic、通义千问的文档都写得不错，示例代码直接能跑。Hugging Face是模型仓库也是社区，找模型、看评测、读讨论都在上面。GitHub上搜awesome-llm能出来一堆整理好的资源列表。遇到具体报错的时候，把错误信息贴到搜索引擎里，大概率有人踩过同样的坑。我还会关注几个技术博客和公众号，更新频率不用高，内容扎实就行。
2.1 任务需求分析与模型能力匹配
选模型这件事，我踩过的坑比吃过的盐还多。最开始我没啥章法，看排行榜谁分高就用谁，结果拿一个千亿参数的大模型去做简单的文本分类，响应慢得让人抓狂，成本还高得离谱。后来我才慢慢明白一个道理：不是最强的模型最适合你，而是最能解决你问题的模型才值得掏钱。你手头的任务到底是啥类型，这个得先拆清楚。是长文本摘要还是短对话？需不需要模型支持函数调用？对多语言有没有要求？对实时性敏感不敏感？这几个问题问下来，模型的候选范围就缩小了一大半。
我一般会把任务需求拆成三个维度来看。第一个是能力维度，你的任务涉及推理、代码、数学还是创意写作，不同模型在这些方向上的强弱差异特别大。有些开源模型在通用对话上表现不错，但一到复杂推理就明显掉链子，这个你得通过实际测试来判断，光看跑分不靠谱。第二个是成本维度，你得算一笔账，按你预估的调用量，每个月在token上的花费是多少，能不能承受。第三个是延迟维度，如果你的应用需要实时交互，那模型的首token延迟和生成速度就很关键，大模型在这方面的劣势很明显。
具体怎么选？我的做法是先框定两三个候选，然后拿真实数据跑一轮小规模测试。比如你要做客服问答，就准备几十条真实用户问题，把不同模型的回答拉出来对比，看哪个更符合你的预期。别嫌麻烦，这一步花的时间后面能帮你省下大量的返工成本。我当初就是跳过了这一步，直接上了个热门模型，结果发现它在我这个垂直领域的术语理解上还不如一个更小的专用模型。另外别忘了关注模型的上下文窗口大小，如果你的文档很长，窗口不够用的话，你后面的分块策略会变得非常复杂。
2.2 账号注册、API密钥、配额与计费准备
我见过太多人卡在注册这一步就放弃了，其实真没那么复杂，但确实有些细节提前知道了能少走弯路。选好模型之后，你得去对应的平台注册账号。国内的通义千问、文心一言、智谱，海外的OpenAI、Anthropic、Google，流程大同小异。邮箱、手机号、验证码，填完就完事了。有一点要注意，有些平台注册的时候需要企业认证或者邀请码，这个你提前看好，别等到要用的时候才发现卡住了。我自己习惯把每个平台的注册信息整理在一个表格里，包括账号、注册邮箱、认证状态，时间长了账号多了真的会乱。
拿到账号之后就是申请API密钥。密钥这东西相当于你的密码，千万不要直接写在代码里然后提交到GitHub上，我身边真有人因为这个被人盗刷了几百刀。正确的做法是放在环境变量里，或者用一个专门的配置文件管理，记得把配置文件加到.gitignore里。大部分平台都支持创建多个密钥，我一般会给不同的项目分配不同的密钥，这样哪个项目出了问题能快速定位，也方便后续做权限隔离和费用追踪。
配额和计费这块，我的建议是刚开始别急着充大钱。大多数平台对新用户都有免费额度，先拿免费额度跑通流程，确认模型效果符合预期之后再考虑付费。付费之前搞清楚几件事：计费单位是按输入token还是输出token分开算的，有没有阶梯定价，有没有最低消费。我现在的习惯是给每个项目设置一个消费上限，很多平台都支持这个功能，到了阈值会自动停掉，避免半夜跑批量任务的时候不小心烧掉太多钱。还有一点，记得定期看账单明细，有时候调用量不大但费用异常，很可能是因为某个循环里多调了几次，这种问题只有看账单才能发现。
2.3 开发环境搭建与依赖安装
环境搭建是我最讨厌的环节，但也是绕不过去的。我自己的经验是，别追求一步到位，先把最小可用的环境跑起来，后面缺什么补什么。Python版本我建议用3.10或者3.11，太老的版本很多新库不支持，太新的版本又容易遇到依赖冲突。管理Python环境用conda或者uv都行，我个人现在更习惯uv，装包速度快得不是一点半点。虚拟环境一定要建，别把所有包装到系统Python里，我当初图省事直接全局安装，后来两个项目依赖的库版本冲突，折腾了大半天才修好。
安装依赖的时候有个小技巧：先只装最核心的几个包。比如调API的话，requests或者官方SDK装一个就够了，别一上来就把langchain、llama-index这些全家桶都装进去，它们虽然方便但依赖链很长，装完容易出各种版本兼容问题。我一般会建一个requirements.txt，把装过的包和版本号记下来，换机器或者跟别人协作的时候直接一键安装，省事很多。至于代理配置，如果你调的是海外平台的API，可能得处理一下网络问题，这个具体方法网上教程很多，我就不展开了，但记得把代理设置放在环境变量里而不是写死在代码里。
编辑器我首选VS Code，插件装Python和Jupyter就够了，调试和写脚本都方便。如果你习惯用PyCharm也没问题，功能更全但占资源多一些。终端我推荐用Windows Terminal或者iTerm2，分屏操作效率高。另外装一个Postman或者用curl也行，排查API问题的时候比在代码里打日志直观多了，能看到完整的请求头和响应体。这些小工具看起来不起眼，但用顺手了能帮你省下不少时间。
2.4 最小可用示例：完成第一次模型调用与验证
这一步是整个教程里我最看重的环节。你不需要理解所有参数，也不需要搭一个完整的项目，只要能发一个请求、拿到模型的回复，就算成功。我当初第一次调通的时候特别兴奋，虽然只是打印了一句“你好，我是AI助手”，但那个瞬间你会觉得前面折腾环境的时间都值了。先跑通，再优化，这个顺序千万别反过来。
我拿一个通用的流程来说。打开你的Python脚本，导入SDK或者直接发HTTP请求，把API密钥从环境变量里读出来，构造一个最简单的消息，用户发一句“你好”，然后把请求发出去。重点检查三件事：密钥有没有正确加载、请求地址对不对、返回结果能不能正常解析。我遇到过密钥末尾多了一个空格导致认证失败的情况，也遇到过请求地址少写了一个版本号返回404，这些错误信息都很明确，看报错提示就能定位。第一次跑不要加流式输出、不要加多轮对话、不要调参数，就最简结构，把链路跑通。
验证的时候我有个小习惯：除了看模型有没有回复，还会打印一下响应里的元数据，比如用了多少token、模型版本号是什么、响应时间大概多少。这几个信息后面做成本估算和效果对比的时候很有用。跑通之后你可以在代码里加一行打印，把完整的响应对象输出出来，看看里面都有哪些字段，这个比看文档印象深得多。最后提醒一点，第一次调通之后马上把代码整理一下，把密钥、模型名、请求地址这些配置项抽出来放到一个单独的地方，别让一个跑通的脚本乱成一团，不然后面扩展的时候你会想重写。
3.1 API基础概念、请求结构与响应格式
我第一次看API文档的时候，脑子是懵的。满屏的JSON结构、各种header字段，完全不知道从哪里下手。后来被坑得多了才慢慢搞明白，API调用本质上就是一趟快递：你把包裹打包好（请求体），贴上快递单（请求头），送到正确的地址（API端点），然后等对方签收处理再给你回执（响应）。拆开看其实就三个东西：地址、头、体。地址决定了你找谁办事，头里面装着身份信息和格式声明，体里面才是你真正想说的话。
拿OpenAI风格的接口举例，一次典型的请求长这样：请求体里最核心的是messages数组，里面每一条消息都要带role和content。role有三种常用值，system用来设定模型的身份和行为边界，user代表你输入的内容，assistant是模型之前回复的内容。我一开始总觉得system消息可有可无，后来发现这玩意儿调好了效果差异巨大，相当于给模型定了个基调。除了messages，还有model字段指定你要调哪个模型，这个必须填。参数类的可选字段先不管，等你把最基本的请求跑通了再说。
响应格式方面，你拿到的也是一个JSON对象，核心关注choices数组里的第一条，里面有个message对象，content就是模型生成的文本内容。外面还包了一层usage信息，告诉你这次花了多少input token和output token，这个数据在做成本核算时非常关键。我最开始只看content，完全忽略了usage和finish_reason这些字段，后来做监控和异常排查的时候才发现这些信息有多重要。finish_reason告诉你模型是因为正常结束还是因为达到max_tokens被截断才停下来的，如果是长度截断你得调整参数或者精简输入。刚上手的时候建议每次调用都把完整响应打印出来看一眼，肉眼熟悉一下字段结构，比读文档快得多。
3.2 认证方式、核心参数与返回结果解析
认证这块其实没什么花头，主流平台基本都是用API密钥。你在请求头里加一个Authorization字段，值写成Bearer加空格加你的密钥，就完事了。有些平台可能用x-api-key这种自定义header，具体看文档说明。我想强调的只有一点：密钥泄露真的会倾家荡产。我有个朋友图方便把密钥写在了前端代码里，上线没几天就被人刷了几百美金的调用量。正确做法是后端代理转发，密钥只放在服务端的环境变量里，前端永远不直接碰密钥。
核心参数我挑几个最常用的说。temperature控制输出的随机程度，值越低越保守稳定，值越高越有创造性。我一般做数据提取类任务用0到0.3，做创意文案用0.7到1.0，根据实际效果微调。max_tokens限制输出长度，防止模型啰嗦个没完还烧你的钱，设置的时候要结合你的业务需求来。top_p和temperature调整一个就行，两个同时调容易互相干扰。还有一个容易忽略的是stop字段，可以指定遇到什么字符就停止生成，做格式约束的时候特别管用。这些参数别一上来就全部调一遍，先默认值跑通，再根据输出效果逐个调整，不然出了问题你都不知道是哪个参数捣的鬼。
结果解析这块，大多数人只取content字段就结束了，但我建议你多关注几个地方。finish_reason前面说了，判断是否被截断。usage里的token数据用来算账。有些平台还会返回id字段，做日志追踪的时候有用，出了问题拿这个id去找平台对线，他们能快速定位到那次请求。另外创建时间戳也记录一下，后面做延迟分析用得上。我自己写了个小函数专门提取这几个字段，每次调用完自动打一行日志，时间长了积累下来的数据能帮你发现很多规律，比如哪些请求特别慢、哪些输入特别费token。养成这个习惯，后面优化的时候你有数据支撑，不用凭感觉拍脑袋。
3.3 流式输出、多轮对话与函数调用
流式输出是我认为体验提升最明显的一个功能。非流式调用你得等模型全部生成完才能拿到结果，有时候等个七八秒页面都是空白的，用户早跑了。流式输出就是模型每生成一个token就推给你，你可以像打字机一样逐字展示。技术上就是把请求参数里的stream设成true，然后处理返回的SSE流，每次收到一个数据块就解析一下提取增量内容拼起来。我一开始处理流式响应的时候踩了个坑：数据块是按行传输的，有时候一个完整的JSON被拆成两半分布在两个块里，你得自己维护一个缓冲区做拼接。处理好了之后那种实时输出的感觉确实很爽，用户等待的焦虑感大幅降低。
多轮对话的本质你得想明白：模型本身没有记忆。每次请求你都得把之前的历史消息完整带上，模型才能理解上下文。所以你要自己维护一个消息列表，每次用户说话就append一条user消息，模型回复了就append一条assistant消息，下次请求把整个列表发过去。听着简单对吧？但消息列表会越来越长，token消耗越来越大，迟早会顶到上下文窗口的上限。我的做法是设一个阈值，当消息条数或者token估算值超过某个线的时候，把早期的消息做摘要或者直接截断，保留最近几轮加上system提示词。这个策略要结合你的业务场景来定，客服场景可能要保留更长的历史，简单问答场景留个五六轮足够了。
函数调用是让模型从聊天机器人变成智能助手的核心机制。你预先定义好一组函数，告诉模型每个函数是干什么的、需要什么参数。模型在对话过程中判断需要调用某个函数时，会返回一个特殊的结构告诉你函数名和参数，你的代码去执行这个函数拿到结果，再把结果回传给模型，模型基于这个结果继续生成最终回复。整个流程走下来，模型就像是有了手脚，能查数据库、能调外部接口、能执行实际操作。我第一次跑通函数调用的时候特别激动，觉得这东西的可能性一下就打开了。不过要注意，函数定义的描述一定要写清楚，模型靠这些描述来判断什么时候该调用哪个函数，描述写得含糊它就会乱调或者漏调。
3.4 错误处理、重试机制与限流应对
错误处理这块，我的血泪教训能写一本书。最常见的错误码就那几个：401是密钥有问题，403是权限不够或者余额不足，404是地址写错了，429是请求太频繁被限流了，500系列是服务端出了问题。401和403你别急着重试，重试也没用，老老实实检查密钥和账户状态。429和500系列可以重试，但重试不能无脑循环，你得加退避策略。我现在的标配是指数退避：第一次等1秒，第二次等2秒，第三次等4秒，最多重试三次，还不行就记日志报错。重试的时候记得加一点随机抖动，不然多个请求同时重试容易形成新的峰值。
限流这事你得提前了解平台的规则。大部分平台是按每分钟请求数或者每分钟token数来限的，具体数值在文档里能找到。我的做法是在客户端做个简单的令牌桶或者滑动窗口计数器，控制自己发出的请求速率，主动避免撞墙。另外收到429响应的时候，仔细看响应头里有没有Retry-After字段，很多平台会告诉你建议等多久再试，照着做就行。我有一次没看这个字段直接重试，结果连续撞了三次429，白白浪费了时间。还有一个小技巧：如果你的调用量比较大，可以把请求分散到多个API密钥上，很多平台对单个密钥有限流但账户整体额度更高，这样能有效提升吞吐。
日志和监控也是错误处理的一部分。我最开始只在代码里print一下错误信息，后来发现根本不够用。你需要记录每次请求的时间、模型名、输入token数、输出token数、响应耗时、状态码、错误信息。这些字段积累下来，你能发现很多潜在问题：某个时间段错误率突然飙升可能是平台在维护，某个特定输入总是触发超时可能是内容触发了内容审核，响应时间逐渐变长可能是你在循环里漏了关闭连接。我用的方案很简单，每次调用写一行结构化日志到文件里，后面用脚本一分析就一目了然。不需要上什么重型监控系统，先把日志写明白，问题排查效率就能提升一大截。
3.5 API调用综合案例与最佳实践
综合案例我拿一个实际做过的项目来说：一个带知识库的客服助手。用户提问后，我先用嵌入模型把问题转成向量，去向量数据库里检索最相关的几条知识，把知识作为上下文拼进system消息里，然后带上最近几轮对话历史一起发给对话模型。模型如果判断需要查询订单状态，就触发函数调用去查业务数据库，拿到结果后生成最终回复。整个链路涉及三个API：嵌入模型、对话模型、还有函数调用逻辑。代码结构上我把每个API调用封装成独立的函数，输入输出都是明确的字典格式，中间用管道串起来。这样哪个环节出了问题，单独测那个函数就行，不用跑整个链路。
最佳实践我总结了几个自己一直在用的。第一，所有配置项抽离到配置文件或者环境变量里，模型名、温度值、max_tokens、重试次数这些全部可配，不同环境用不同配置。第二，给每次请求打一个唯一trace_id，贯穿日志和响应，排查问题时一搜就全串起来了。第三，写一个统一的API调用封装函数，把重试、超时、日志、错误处理都包在里面，业务代码只管传参和取结果。第四，对输出做校验，模型生成的内容不一定符合你的格式要求，比如你让它返回JSON，它可能给你加一段解释文字在前面，简单的做法是用正则提取，严格的做法是做JSON schema校验加自动修复重试。
最后一个实践可能听起来有点反直觉：别过度依赖模型的一次输出。我的经验是同一个问题跑三次取最稳定的那个结果，或者在关键场景用两个不同模型交叉验证，效果比单次调用好很多。代价是成本翻倍，所以你得权衡。对于高价值的任务比如合同审核、代码生成，多跑几次是值得的。对于普通的闲聊问答，单次就够了。我现在的做法是在代码里加一个quality_check函数，对模型输出做基础的质量判断，不合格就自动重试一次并调整参数，合格就直接用。这套机制跑下来，线上输出的稳定性提升非常明显，用户投诉率降了不止一半。你可以根据自己的业务场景设计类似的兜底逻辑，核心思路就是不要把鸡蛋放在一个篮子里。
4.1 本地部署适用场景与硬件资源评估
我为什么会折腾本地部署？说白了就两个字：安心。之前用云端API跑一些涉及客户数据的任务，每次把敏感信息发出去心里都打鼓，虽然平台都说不留存，但总归不是自己手里攥着的东西。后来接了个项目要做医疗问诊辅助，数据绝对不能出内网，这才硬着头皮开始研究本地部署。除了隐私合规，还有几个场景也特别适合本地跑：你想对模型做深度微调的时候，云端API根本不给你这个权限；网络不稳定或者需要离线运行的场景，本地部署是唯一选择；调用量特别大的时候，算下来长期成本比按token付费便宜不少。不过我也得说句实话，本地部署的折腾成本不低，如果你就是做个demo或者日调用量几百次，云端API省心太多了。
硬件这块我踩过的坑最多。最开始我天真的以为有个好点的显卡就能跑，结果发现显存才是真正的门槛。7B参数量的模型，用16位精度加载，光模型权重就要吃掉差不多14GB显存，加上推理过程中的KV Cache和中间激活值，没个16GB显存的卡根本玩不转。我当时手里只有一张8GB的卡，硬跑7B模型直接爆显存，后来只能上量化才勉强滑起来。你要是想跑13B以上的模型，建议显存往24GB以上准备，RTX 3090或者4090这种级别的卡比较现实。当然也可以用多卡，但我个人觉得多卡调试的麻烦程度远超单卡。
除了显存，内存和硬盘也别忽视。模型加载的时候会先读到内存里，特别是用CPU推理或者做模型转换的时候，内存不够直接卡死。我的经验是系统内存至少要是模型文件大小的两倍，比如你下一个13B的模型文件大概26GB，那你的内存最好有64GB才比较从容。硬盘方面现在模型动辄几个G到几十个G，SSD是必须的，机械硬盘加载模型那种等待感会让你怀疑人生。还有电源和散热，跑大模型的时候显卡满载功耗可不低，我有个朋友电源功率不够，一跑推理就重启，排查了半天才发现是电源的锅。
再补充一个容易被忽略的点：你到底需不需要GPU。如果你的场景是离线批处理、对延迟不敏感，用CPU跑量化后的模型完全可行，就是慢一点。我用一台没有独显的笔记本跑过4B量化的模型，生成速度大概每秒三四个token，写个文案、做个总结够用了。你要是做实时对话或者高并发服务，那GPU就是刚需。评估硬件的时候先问自己一个问题：我要的是能用还是好用？能用的话老设备凑合也能跑，好用的话该花的钱省不了。
4.2 模型获取、模型格式与推理框架选择
模型从哪儿下？我主要用两个地方：Hugging Face和国内的ModelScope。Hugging Face上模型最全，基本上你听过的开源模型都能找到，但国内下载速度有时候感人，大文件经常断。ModelScope是阿里搞的，国内下载速度快很多，主流开源模型基本都有镜像。我现在的习惯是先去ModelScope找，找不到再去Hugging Face。下载方式可以用网页直接下，也可以用git lfs或者huggingface-cli这些工具，大模型文件建议用工具下，支持断点续传，不然下到一半断了能气死你。
模型格式这块刚开始把我绕晕了。最常见的是safetensors格式，Hugging Face上默认就是这个，安全性和加载速度都不错。还有GGUF格式，这是llama.cpp搞出来的，专门为量化推理设计的，一个文件包含全部权重，用起来特别方便，Ollama和llama.cpp都吃这个格式。老一点的还有PyTorch的bin格式和GGML格式，现在新模型基本不怎么用了。我的建议是：如果你用llama.cpp或者Ollama这条路线，直接找GGUF格式的模型文件，省去转换的麻烦。如果你用Transformers或者vLLM，那就用safetensors原始格式。别下错格式，不然还得花时间转换，转换过程本身也可能出问题。
推理框架怎么选，这个取决于你的需求和技术栈。我列一下自己用过的几个。Ollama是上手最简单的，一条命令拉模型一条命令跑起来，适合快速验证和本地开发，缺点是定制化能力弱一些。llama.cpp是C++写的，性能很好，CPU上也能跑得动，量化支持最完善，适合资源紧张的环境。vLLM是冲着高并发去的，吞吐量非常猛，适合做服务端部署，但它对硬件要求高，基本得是NVIDIA显卡。Transformers是Hugging Face的官方库，灵活度最高，什么模型都能跑，但推理性能一般，适合做研究和微调。我个人的组合是：开发调试用Ollama图省事，正式服务用vLLM拼吞吐，资源受限的边缘设备用llama.cpp。
选框架的时候还有一个因素要考虑：社区活跃度和文档质量。我一开始用过一个比较冷门的框架，遇到问题搜都搜不到解决方案，官方文档写得跟天书一样，最后弃坑了。现在主流这几个框架社区都很活跃，GitHub上issue回复也快，遇到坑基本都能找到人踩过。你选框架之前去GitHub看一眼star数和最近的commit频率，太长时间不更新的项目慎用，模型迭代这么快，框架跟不上很容易出兼容性问题。
4.3 环境配置、依赖安装与服务启动
环境配置是本地部署最烦人的环节，没有之一。我的血泪建议是：一定要用虚拟环境，conda或者venv都行，千万别在系统Python里直接装。不同模型和框架对依赖版本的要求经常打架，不用虚拟环境迟早会遇到版本冲突。我自己习惯用conda，因为可以很方便地管理不同Python版本。建环境的命令很简单，conda create -n llm python=3.11这样就行，Python版本别太老也别太新，3.10到3.11这个区间兼容性最好。
如果你用GPU推理，CUDA和cuDNN的版本匹配是第一个大坑。框架文档里通常会写清楚推荐什么CUDA版本，照着装就行。我遇到过一次装完CUDA之后PyTorch识别不到GPU，折腾了一下午才发现是驱动版本太老，CUDA版本和驱动不匹配。建议装之前先跑nvidia-smi看一下驱动支持的CUDA版本上限，别超过那个上限。pip装PyTorch的时候记得去官网查对应的安装命令，那个命令里带了CUDA版本的标识，比如cu121这种，选错了就白装。
拿Ollama举例说下服务启动有多简单。去官网下对应系统的安装包，双击安装，然后在终端里ollama run llama3这样一条命令，它就会自动下载模型并启动服务，直接进入对话界面。就这么简单，我第一次用的时候都有点不敢相信。Ollama默认监听11434端口，后台会跑一个服务进程，你可以用ollama serve手动启动服务，用ollama list看已经下载了哪些模型，用ollama pull拉新模型。对于不想折腾的人来说，Ollama是目前本地部署体验最顺滑的方案。
如果你走vLLM或者Transformers路线，步骤会多一些。vLLM的安装是pip install vllm，然后启动命令类似python -m vllm.entrypoints.openai.api_server --model 模型路径 --port 8000。它启动之后会暴露一个兼容OpenAI接口的服务，你之前写的API调用代码基本改个地址就能直接用，这点特别爽。Transformers路线就更原始一些，自己写个脚本加载模型和tokenizer，然后调用generate方法。这种方式灵活但繁琐，你需要自己处理批处理、并发、显存管理这些事，我不太推荐拿它做生产部署。
启动服务之后别急着高兴，先做一轮基本验证。用curl或者Python脚本发一个简单的请求，看看能不能正常返回。再检查一下显存占用是否正常，用nvidia-smi看一下显存有没有爆，GPU利用率是否合理。如果响应特别慢或者直接报OOM，那就要回头检查模型精度是不是太高、并发数是不是设大了。我现在的习惯是每次启动新服务先用一个极简的请求跑通，确认链路没问题再开始搞复杂的东西，避免一上来就调一大坨代码结果不知道错在哪儿。
4.4 本地推理服务封装与客户端调用
服务能跑起来是一回事，好用是另一回事。直接把裸的推理进程暴露出去问题很多：没有认证、没有限流、没有统一接口格式、异常处理全靠运气。我通常会在模型服务前面包一层自己的API服务，用FastAPI或者Flask写，把认证、日志、参数校验这些逻辑都加上。这层薄薄的封装花不了多少时间，但后面维护和扩展的时候能救命。我见过有人直接把vLLM的8000端口暴露到公网，结果被人当免费API刷，虽然本地部署不直接产生费用，但GPU被打满之后你自己的服务全卡死了。
封装的核心思路是对外提供统一的接口契约，对内适配不同的推理框架。比如我设计一个/v1/chat/completions接口，请求体格式参照OpenAI的标准，这样客户端代码不用关心后端到底用的是Ollama还是vLLM。封装层里做几件事：校验API key、记录请求日志、做输入长度检查、设置超时、捕获推理异常并转成友好的错误码。这一套下来，你的本地服务用起来就跟云端API差不多了，迁移成本几乎为零。我现在的项目里切换云端和本地只要改一个base_url就行，特别方便。
客户端调用这块，如果你用的是Ollama，直接用它的Python库就行，pip install ollama，然后几句话就能跑通。代码大概长这样：import ollama，然后response = ollama.chat(model='llama3', messages=[{'role':'user','content':'你好'}])，返回结果里取response['message']['content']就是了。如果你走的是兼容OpenAI接口的方案，那直接用openai这个库，把base_url换成你自己的地址，api_key随便填一个，调用方式跟调云端API一模一样。这种一致性对我来说太重要了，我不想为本地部署单独维护一套客户端代码。
流式输出在本地部署里同样支持得很好。Ollama的chat接口传stream=True就能拿到生成器，逐块迭代输出。vLLM的OpenAI兼容接口也支持stream参数。我用FastAPI封装的时候会用StreamingResponse把生成器的内容透传给前端，做一个打字机效果。这里有个细节要注意：流式返回的时候如果客户端提前断开连接，服务端要能及时取消推理任务释放显存，否则跑几次就把显存占满了。我之前的代码没处理这个，跑了一晚上服务直接挂了，后来加了连接状态检测才解决。
再聊聊并发的问题。本地部署和云端最大的区别就是资源是有限的，你没法像云端那样无限扩容。当多个请求同时打进来的时候，显存不够就直接排队或者报错。我的处理方式是在封装层加一个简单的队列和并发上限，超过上限的请求让它等待或者直接返回繁忙状态，别硬塞进去把服务搞崩。vLLM本身有不错的批处理和调度能力，可以设置--max-num-seqs参数来控制同时处理的请求数。Ollama也有类似的环境变量可以调。这块要根据你的显存大小和模型大小来试探，我一般是先设个保守值，然后压测往上加，找到稳定运行的上限。
4.5 量化、性能优化与资源监控
量化是本地部署的救命稻草，这话一点都不夸张。我最早跑7B模型用全精度直接爆显存，后来换成4bit量化，显存占用从16GB降到了5GB左右，一张8GB的卡就轻松跑起来了。量化的本质是用更低的数值精度来表示模型权重，从16位浮点降到8位整数或者4位整数。损失的精度通常比你想的小，我用4bit量化的模型做日常问答和文本总结，效果跟全精度的差异几乎感知不到。当然做代码生成或者数学推理这类精确任务的时候，量化的劣势会稍微明显一些，但也不是不能用。
量化方案我常用的就几种。GGUF格式内置了各种量化等级，从Q2到Q8都有，数字越大精度越高体积也越大。我一般用Q4_K_M这个档位，在精度和体积之间平衡得比较好。再低的话Q3或者Q2会明显感觉到输出质量下降，尤其是长文本生成的时候容易胡言乱语。如果你想再压一压，可以试试AWQ或者GPTQ这两种量化方法，它们专门针对GPU推理优化过，4bit下效果比GGUF的一些低档位好。量化不是越狠越好，我踩过的坑是贪便宜上了2bit量化，结果模型经常前言不搭后语，省下来的显存全被反复重试浪费回去了。
性能优化有几个立竿见影的手段。第一个是调batch size，vLLM里有--max-num-seqs参数，Ollama有OLLAMA_NUM_PARALLEL，调大了吞吐量上去了但单次延迟可能变长，得根据场景权衡。第二个是控制上下文长度，把max_tokens和上下文窗口设小一点，KV Cache占用会显著下降，这个对显存的影响特别大。我有次发现服务跑一段时间就慢得不行，查了半天发现是上下文窗口设太大了，每个请求的KV Cache都堆得很高。第三个是保持模型常驻显存，别让它在换入换出之间反复横跳，vLLM的--gpu-memory-utilization参数可以控制预分配的显存比例，调好了能避免碎片化。
资源监控这块，nvidia-smi是最基本的，看显存占用和GPU利用率。但只盯着这个不够，我建议再配上几个指标：请求延迟的分布、每秒处理的token数、错误率、队列长度。这些数据我一般用Prometheus加Grafana来收集展示，vLLM本身有metrics接口可以直接暴露这些数据。如果你不想搞那么重，简单点用Python的psutil和pynvml定时采样写日志也行。我有一次线上服务突然变慢，看监控发现GPU利用率掉到了10%以下但显存占用很高，排查出来是某个请求的输入特别长，把显存吃满了导致其他请求全部排队，这种问题光看日志很难发现。
最后说几个容易忽略的优化点。模型加载的时候用memory mapping能加快启动速度，尤其是从磁盘加载大模型文件的时候。推理服务用到的embedding或者rerank模型尽量跟对话模型放在同一个服务里共享显存管理，分开部署反而浪费资源。还有定期清理缓存和日志文件，本地部署的机器硬盘通常没多大，模型文件和日志堆多了容易把盘吃满。我现在的习惯是每周检查一次磁盘和显存的使用趋势，别等到服务挂了再去找原因。
5.1 提示词设计与输出质量控制
提示词这件事我一开始也觉得玄学，后来被坑多了才慢慢摸出门道。我最早上手的时候就是随手丢一句话给模型，返回的东西有时候能用有时候离谱，完全看运气。后来我把提示词当成代码来写，固定结构分三块：角色设定、任务描述、输出约束。角色设定告诉模型它是谁，任务描述说清楚要干什么，输出约束把格式钉死。这三样写明白之后，输出稳定性肉眼可见地往上走。我现在写提示词会先想清楚一件事：我希望拿到什么样的结果，然后用最直白的话把它描述出来，别整那些花里胡哨的形容词。
光靠一次写好的提示词远远不够，我见过太多人写一版就扔那儿不管了。提示词是需要反复迭代的东西，我的做法是准备二十来条典型输入，每次改完提示词就跑一遍，看看哪些过了哪些没过。失败的那些拿出来分析，是模型没理解任务还是输出格式跑偏了。有时候只需要加一句示例，有时候要把任务拆成两步。我印象很深的一次，让模型从合同里提取关键条款，直接问它老是漏项，后来改成先让它列出所有条款标题，再逐条提取内容，准确率一下就上去了。这种拆解思路在复杂任务里特别好使。
输出质量控制这块，我吃过的大亏就是完全信任模型返回的原始文本。现在我的做法是让模型输出结构化数据，JSON或者固定标记包裹的格式，然后代码里做一层校验。字段缺失、类型不对、超出范围，这些都在代码层拦掉，校验不通过就带着错误信息让模型重试一次。重试也搞不定的话就走兜底逻辑，返回一个默认值或者提示用户换种问法。这套机制加上去之后，前端那边基本没再抱怨过解析报错。另外我会在提示词里明确说“只输出JSON，不要输出任何解释”，有时候模型还是忍不住加两句废话，得用正则把JSON块抠出来，这个兜底我建议都加上。
5.2 模型应用集成模式与工程化实践
集成模式这事儿得看你的规模。小项目直接在一个业务函数里调API就行，代码简单跑得快。但我见过不少项目一开始图省事把模型调用散落在各个业务代码里，后来要换模型或者加限流，得满项目找调用点，改起来想死。我现在习惯是加一层封装，把所有模型调用收敛到一个类或者一个服务里，业务层只依赖一个接口。换模型、改参数、加监控都在这层里做，业务代码基本不用动。这层封装不用写得多复杂，几十行代码就够，但省下来的维护成本是实打实的。
工程化里头我觉得最容易被忽略的是超时和重试。模型调用跟普通接口不一样，有时候一个请求卡二十秒才返回，有时候直接给你来个500。我的配置是连接超时三秒，读取超时按场景设，普通对话三十秒，长文本生成给到两分钟。重试只对网络错误和限流错误做，参数错误和内容审核拒绝重试也没用。重试次数我一般设两次，带上指数退避。还有一点特别重要，重试一定要做幂等设计，别让用户看到重复扣费或者重复提交。异步任务的话我会用消息队列把请求和结果解耦，前端轮询或者走WebSocket推结果，体验好很多。
再聊聊配置管理和多模型路由。我现在的项目里经常同时接两三个模型，简单的任务走小模型省钱，复杂的走大模型保效果，或者一个主用一个备用。这块我是在配置中心里维护一张路由表，按场景、按用户等级、按时间窗口来分流。比如白天高峰期对话走小模型，晚上批处理任务走大模型。配置文件别硬编码在代码里，用环境变量或者配置中心注入，不然改个参数还得重新部署。我有一次线上模型供应商挂了，因为路由配置是热加载的，五分钟内切到备用模型，用户几乎没感知到。这种容灾能力平时看不出来，出事的时候能救命。
5.3 成本、延迟与效果之间的权衡
成本这事我是被账单教育过的。刚开始做项目的时候什么都用最大的模型，效果确实好，月底账单一出来老板脸都绿了。后来我做了一轮分析，发现大部分请求根本不需要大模型，简单的分类、改写、摘要用小模型完全够用。我现在会把请求分成三档：轻量任务走小模型，一般任务走中模型，只有那些真正复杂的推理和长文本生成才用大模型。这个分档逻辑不一定要靠人工判断，可以用一个轻量的分类器或者规则先做路由。算下来成本能砍掉一大半，效果下降的感知其实很有限。
延迟这边我有过很深的体会。用户对响应速度的忍耐度比想象中低，超过三秒就开始烦躁。影响延迟的因素很多，模型大小是一方面，输出长度是另一方面，还有网络链路和并发排队。我的优化顺序是这样的：先做流式输出让用户立刻看到字，体验上先赢一半；再控制输出长度，提示词里明确说“简洁回答，不超过两百字”，别让模型洋洋洒洒写一堆；然后考虑把高频请求的结果缓存起来，相同或者相似的问题直接命中缓存。缓存命中率我现在的项目里大概能到三成，这部分的延迟几乎为零。
效果、成本、延迟这三者就是个跷跷板，不可能全都要。我的经验是先定清楚底线：效果不能低于某个标准，延迟不能超过某个阈值，在这两个约束下再去找成本最优的方案。有些场景其实可以牺牲一点效果换速度，比如内部工具的辅助写作，快比完美重要。有些场景必须死磕效果，比如合规审查和医疗建议，慢一点贵一点用户也能接受。这个判断得跟业务方一起定，不能拍脑袋。我见过技术团队闷头优化成本，结果输出质量掉了被业务方投诉，最后还得加回去，白折腾一场。
5.4 数据安全、隐私保护与合规要点
数据安全这块我现在的态度是宁可麻烦也不能出事。最基础的一条：发给模型的数据里不能有身份证号、手机号、银行卡这类敏感信息。我的做法是在请求进入模型之前加一层脱敏处理，正则匹配到敏感信息就替换成占位符，等模型返回结果之后再根据映射表还原。这个映射表只存在内存里，请求结束就销毁，不落盘。有人可能觉得这样会影响模型理解上下文，实测下来影响很小，模型对占位符的推理能力比想象中好。另外日志里绝对不能打原始输入输出，我见过有团队把完整对话打进日志，后来日志泄露导致用户隐私曝光，这种事故一出就是大事。
合规方面要看你的业务地域和行业。做国内业务的话个人信息保护法得研究一下，用户的知情同意、数据最小化这些原则要落实到产品设计里。做海外业务还要考虑GDPR那些。我一般会跟法务过一遍数据流向图，从用户输入到模型返回，中间每个环节数据存在哪里、存多久、谁能访问，都列清楚。有个容易忽略的点是模型供应商的数据使用条款，有些平台会拿你的数据去训练模型，这个得在合同里明确禁止。本地部署最大的好处就是数据不外流，但本地服务器本身的安全防护也得做到位，别自家机房被拖库了还怪云端。
再补一个我踩过的坑：删除权。用户要求删除个人数据的时候，你得确保数据是真的删干净了，包括缓存、备份、日志、向量数据库里的embedding。我之前的项目里把对话存到了向量数据库做检索，用户要求删除的时候只删了主表，忘了删向量那边的记录，后来做合规审计才发现。现在我的做法是设计数据存储的时候就考虑好删除链路，每个存储位置都打上用户标识，删除的时候按标识全链路清理。定期还要做一次数据盘点，该清的清，该归档的归档，别让数据无限堆积，堆得越多风险越大。
5.5 常见问题排查与迭代优化方法
排查模型应用的问题，最怕的就是“有时候好有时候不好”这种。我的习惯是把每次调用的关键信息都记下来：请求ID、模型版本、提示词版本、输入输出长度、耗时、重试次数、是否命中缓存。有了这些数据，出问题的时候能快速定位是模型的问题、提示词的问题还是链路的问题。有一次线上突然出现一批格式错误，看日志发现是某个时间点开始提示词版本变了，回滚之后立刻恢复。没有这些记录的话，这种问题能查一整天。
模型输出不稳定是最高频的问题。同样的输入今天返回正常明天就胡说八道，这种情况我一般先看是不是温度参数太高了，做确定性任务的时候温度直接调到零。如果温度没问题，就检查提示词里有没有歧义，模型对模糊指令的发挥空间太大。还有一种情况是输入本身触发了模型的某些偏见，这种得靠扩充测试用例来覆盖。我的做法是维护一个评测集，每次改提示词、换模型、调参数都跑一遍，看整体通过率有没有下降。评测集不用很大，一两百条覆盖核心场景就够了，但每条都得是真实出现过的案例，编造的测试数据没意义。
迭代优化的节奏我一般是小步快跑。每次只改一个变量，改完上灰度环境跑一两天，看监控指标和用户反馈，没问题再全量。大头改动用A/B测试，一部分流量走新版本一部分走老版本，对比效果和成本。我见过团队憋大招，改了三个月一次性上线，结果效果没提升还引入了新bug，回滚都麻烦。另外别忽略用户反馈这个渠道，我现在的产品里加了个点赞点踩的按钮，踩的时候让用户填一句原因，这些数据比什么指标都真实。定期把踩的数据拉出来看，往往能发现模型理解不了的表达方式或者边界场景，针对性地补充提示词和测试用例，效果提升特别快。
最后说一个心态上的事。模型应用这东西没有一劳永逸的时候，模型在更新，用户输入在变化，业务需求也在变。我现在的做法是每个月做一次回顾，看看这个月的错误率趋势、成本变化、用户反馈，列几个优先级高的优化点排进下个迭代。别等到出事故了才想起来优化，平时一点点打磨，系统才会越来越稳。我刚开始做的时候总想一步到位，后来发现持续迭代才是常态，接受这个设定之后反而没那么焦虑了。
