1. 从API调用到RAG部署我踩过的那些坑去年年初我刚开始系统性地折腾大模型应用开发那时候手里就一个DeepSeek的API Key觉得调用大模型嘛无非就是发个HTTP请求、拿个返回结果能有多难。结果从第一个Demo跑通到后来把一套完整的RAG知识库部署上线中间踩的坑比我前三年写业务代码加起来都多。这篇文章不是教程是我自己复盘下来的踩坑记录把从API调用、Prompt设计、RAG搭建到最终部署这条链路上遇到的实际问题和解决思路都摊开讲一遍。如果你也是刚入门大模型应用开发或者已经能跑通简单的API调用但一到RAG就各种报错那这篇内容应该能帮你省下不少查文档和试错的时间。我会按学习路线的顺序来讲每个阶段说清楚三件事我当时怎么做的、遇到了什么问题、后来怎么解决的。涉及到的技术点包括API调用的鉴权与错误处理、Prompt工程的实际写法、RAG的检索与生成链路、以及本地化部署时的模型选型和资源配置。先说一下我的背景方便你对标。我有Python后端开发经验对Flask和FastAPI比较熟之前没接触过向量数据库和Embedding模型GPU资源只有一张RTX 3060 12G的卡。整个学习路线大概花了三个月前一个月在API调用和Prompt上反复折腾后两个月基本都在跟RAG的检索质量和部署环境较劲。2. API调用阶段那些让人抓狂的报错2.1 第一个401API Key的坑比想象中多我拿到的第一个API Key是DeepSeek的按照官方文档写了个最简单的Python脚本import requests url https://api.deepseek.com/v1/chat/completions headers { Authorization: Bearer sk-xxxxxxxxxxxxxxxx, Content-Type: application/json } data { model: deepseek-chat, messages: [{role: user, content: 你好}] } resp requests.post(url, headersheaders, jsondata) print(resp.json())跑出来直接报unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****。我当时第一反应是Key复制错了反复对了三遍确认没问题。后来才发现问题出在两个地方一是Key的前后可能有空格从网页复制的时候很容易带上二是有些平台的Key需要激活或者绑定支付方式之后才能用。提示拿到API Key之后先做一次最简单的curl测试排除代码层面的问题。如果curl也报401那就是Key本身的问题别在代码里浪费时间。排查401的步骤我后来总结成了一个固定流程先用curl直接测排除代码问题然后检查Key的格式确认没有多余空格和换行再确认账户状态有些平台新注册的Key需要等几分钟才生效最后看请求的URL是不是对的不同平台的endpoint路径不一样有的带/v1有的不带。2.2 400错误上下文长度超限的暴力解法有一次我往对话里塞了一篇很长的技术文档想让它帮我总结结果直接报api error: 400 this models maximum context length is 1048576 tokens。这个报错信息其实说得很清楚就是输入太长了。但问题是我怎么知道我的输入到底有多少token我的解决办法是装了一个tiktoken库来估算token数量import tiktoken def count_tokens(text, modelgpt-4): enc tiktoken.encoding_for_model(model) return len(enc.encode(text)) # 对于中文大概1个汉字约等于1.5-2个token text 你的长文本内容... print(f估算token数: {count_tokens(text)})但这里有个坑不同模型的tokenizer不一样tiktoken对OpenAI系列的模型比较准对国产模型的估算会有偏差。我后来养成的习惯是在发送请求之前先做一次长度检查如果超过模型上限的80%就先做一轮摘要或者分段处理。对于超长文本的处理我试过几种方案。最简单的是直接截断但会丢信息。稍微好一点的是分段摘要把长文档切成若干段每段单独摘要再把摘要拼起来。最靠谱的还是上RAG把文档存到向量数据库里需要的时候检索相关片段这样既不会超长又能保留关键信息。2.3 免费API的限流与重试策略刚开始学的时候我到处找免费的大模型API试过好几个平台。免费额度确实能用但限流很严重经常报429。我一开始没做重试程序直接崩了。后来加了一个简单的指数退避重试import time import requests def call_api_with_retry(url, headers, data, max_retries5): for attempt in range(max_retries): try: resp requests.post(url, headersheaders, jsondata, timeout30) if resp.status_code 429: wait 2 ** attempt print(f限流等待{wait}秒后重试) time.sleep(wait) continue return resp.json() except requests.exceptions.Timeout: print(f超时第{attempt1}次重试) time.sleep(2 ** attempt) raise Exception(重试次数用尽)这个重试逻辑后来成了我所有API调用代码的标配。另外还有一个经验免费API的响应时间波动很大有时候几秒有时候几十秒所以timeout一定要设不然程序会卡死。2.4 不同平台API的差异对比学路线中我陆续试了好几个平台的API包括DeepSeek、讯飞星火、以及通过OpenRouter调用的各种模型。每个平台的API格式都有差异这里整理一个对比平台鉴权方式请求格式特点DeepSeekBearer TokenOpenAI兼容便宜中文好推荐入门讯飞星火API Key Secret自有格式需要签名稍微复杂OpenRouterBearer TokenOpenAI兼容模型多但价格参差Ollama本地无OpenAI兼容免费但吃硬件我建议新手先从DeepSeek的API入手因为它的格式跟OpenAI完全兼容网上大部分教程都能直接套用。等你熟悉了基本的调用流程再去试其他平台。3. Prompt工程从瞎写到有章法3.1 我踩过的Prompt坑刚开始写Prompt的时候我就是直接把问题扔进去比如帮我写一个Python函数。结果出来的代码质量参差不齐有时候能跑有时候不能跑。后来我才意识到Prompt的质量直接决定了输出的质量。我遇到过一个很典型的问题就是Prompt被平台的安全审核拦截了报invalid prompt: your prompt was flagged as potentially violating our usage policy。那次是我在做一个文本分类的任务Prompt里包含了一些敏感词的示例结果被拦了。解决办法是把示例改成更中性的表述或者用占位符代替敏感内容。还有一个坑是Prompt太长导致模型忘记前面的指令。我试过写一个很长的System Prompt里面塞了十几条规则结果模型只记住了最后几条。后来我把规则精简到5条以内并且把最重要的规则放在最前面和最后面效果好了很多。3.2 结构化Prompt的写法经过反复试错我总结出了一个比较稳定的Prompt结构# 角色 你是一个资深的Python后端工程师擅长编写高质量、可维护的代码。 # 任务 根据用户的需求编写Python函数。 # 约束 1. 代码必须包含类型注解 2. 必须处理异常情况 3. 函数不超过50行 4. 添加简洁的注释 # 输出格式 直接输出代码不需要额外的解释。 # 用户需求 {user_input}这个结构的核心思路是把角色、任务、约束、输出格式分开写让模型能清晰地理解每个部分的要求。实测下来这种写法的输出稳定性比一大段自然语言描述要高不少。3.3 Few-shot示例的正确用法对于分类、抽取这类任务Few-shot示例的效果非常明显。但示例的选择有讲究我试过几种方案随机选示例效果一般有时候模型会学到错误的模式选最典型的示例效果好但需要人工挑选选边界情况的示例对提升模型的鲁棒性很有帮助我现在的做法是每个类别选2-3个示例其中至少有一个是边界情况。比如做一个情感分类的任务除了明显的正面和负面示例还会加一个中性偏正面的模糊示例这样模型对边界情况的判断会准很多。注意Few-shot示例不是越多越好。我试过放10个示例结果模型开始抄示例的输出格式反而忽略了实际输入。一般来说3-5个示例是比较合适的。3.4 Prompt版本管理这个是我踩了坑之后才养成的习惯。一开始我改Prompt就是直接在代码里改改完之后发现效果变差了想回退却找不到之前的版本。后来我把Prompt单独抽出来放在一个文件里用Git管理每次改动都写清楚改了什么、为什么改。# prompts/classify_v3.txt # 修改记录v3增加了边界情况的示例分类准确率从82%提升到89%这个习惯看起来简单但在后期调试的时候帮了我大忙。特别是做RAG的时候检索和生成两个环节的Prompt需要反复调整没有版本管理根本记不住哪个版本效果好。4. RAG实战从零搭一个能用的知识库4.1 RAG的基本链路RAG的核心思路其实不复杂把文档切成小块存到向量数据库里用户提问的时候先检索相关片段再把片段和问题一起发给大模型生成回答。但真正动手做的时候每个环节都有坑。我的第一条RAG链路是这样的from langchain.document_loaders import TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain.embeddings import HuggingFaceEmbeddings from langchain.vectorstores import Chroma # 1. 加载文档 loader TextLoader(knowledge.txt) docs loader.load() # 2. 切分文档 splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50 ) chunks splitter.split_documents(docs) # 3. 向量化并存储 embeddings HuggingFaceEmbeddings(model_nameBAAI/bge-small-zh) vectorstore Chroma.from_documents(chunks, embeddings, persist_directory./db) # 4. 检索 results vectorstore.similarity_search(用户的问题, k3)这段代码看起来很简单但实际跑起来问题一堆。首先是Embedding模型下载慢HuggingFace的模型在国内下载经常超时。其次是切分参数不好定chunk_size设大了检索不精准设小了上下文不完整。4.2 文档切分最容易被忽视的关键环节文档切分是RAG里最不起眼但影响最大的环节。我一开始用固定长度切分500个字符一块结果经常把一句话切成两半检索出来的片段读都读不通。后来我改用了按语义切分优先在段落、句子边界处切分splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap100, separators[\n\n, \n, 。, , , , , , ] )separators的顺序很重要它会优先尝试用前面的分隔符切分。对于中文文档我把句号、问号、感叹号这些句子结束符放在前面这样切出来的块语义更完整。chunk_overlap也值得说一下。我一开始设的是0结果检索的时候经常漏掉跨块的信息。后来改成chunk_size的20%左右也就是100个字符效果好了很多。overlap的作用是让相邻的块之间有重叠这样即使关键信息刚好在边界上也能被检索到。4.3 Embedding模型选型中文场景的实测对比Embedding模型的选择直接决定了检索质量。我试过好几个模型这里把实测结果整理一下模型维度中文效果速度显存占用BAAI/bge-small-zh512不错快低BAAI/bge-base-zh768好中等中等BAAI/bge-large-zh1024很好慢高text-embedding-ada-0021536好快无API我的建议是如果显存有限比如只有8G用bge-small-zh就够了检索效果和large版本的差距没有想象中那么大。如果追求极致效果且显存充足bge-large-zh是更好的选择。用API的话OpenAI的text-embedding-ada-002很稳但需要付费。还有一个细节bge系列的模型在检索的时候需要加指令前缀。查询的时候加为这个句子生成表示以用于检索相关文章文档侧不加。这个细节官方文档里有写但很容易被忽略加上之后检索准确率能提升几个百分点。4.4 向量数据库选型Chroma vs Milvus vs FAISS向量数据库的选择我纠结了很久最后把三个主流的都试了一遍Chroma最大的优点是简单几行代码就能跑起来适合快速验证。但它的性能一般数据量大了之后检索会变慢。我试过存10万条数据检索延迟大概在200ms左右还能接受但再往上就不好说了。Milvus功能最全支持分布式部署性能也好。但部署复杂度高我用Docker Compose搭了一套光是配置文件就调了半天。如果你的数据量在百万级以上或者需要多用户并发访问Milvus是更好的选择。FAISS是Facebook开源的向量检索库性能很好但它是库不是服务需要自己封装成API。适合对性能要求高、且愿意自己写一层封装的场景。我最后选的是Chroma因为我的知识库规模不大几千条文档Chroma完全够用而且开发效率高。等数据量上来了再迁移到Milvus也不迟。4.5 检索策略优化从Top-K到混合检索基础的相似度检索有个问题就是有时候检索出来的片段跟问题语义相似但实际不相关。我试过几种优化方案第一种是调整Top-K。K太小会漏信息K太大又会引入噪声。我试了K3、5、10最后发现K5是个比较平衡的值。但K的值跟文档切分的粒度有关chunk_size小的时候K可以大一点反之则小一点。第二种是加相似度阈值。只保留相似度高于某个阈值的片段低于阈值的直接丢掉。这个阈值需要根据实际数据调我一般从0.7开始试。第三种是混合检索把向量检索和关键词检索结合起来。向量检索擅长语义匹配关键词检索擅长精确匹配两者互补。我用的是BM25做关键词检索然后跟向量检索的结果做加权融合def hybrid_search(query, vectorstore, bm25_index, alpha0.5, k5): # 向量检索 vector_results vectorstore.similarity_search_with_score(query, kk*2) # 关键词检索 bm25_results bm25_index.search(query, kk*2) # 融合排序 combined {} for doc, score in vector_results: combined[doc.page_content] alpha * (1 - score) for doc, score in bm25_results: if doc.page_content in combined: combined[doc.page_content] (1 - alpha) * score else: combined[doc.page_content] (1 - alpha) * score # 返回Top-K sorted_results sorted(combined.items(), keylambda x: x[1], reverseTrue) return sorted_results[:k]混合检索的效果确实比单一检索好但实现复杂度也上去了。我的建议是先把基础检索跑通遇到瓶颈了再考虑混合检索。4.6 RAG的Prompt设计检索到相关片段之后怎么把它们和问题一起发给大模型也是有讲究的。我一开始的Prompt是这样的根据以下内容回答问题 {context} 问题{question}结果模型经常编造答案明明context里没有的信息它也能编出来。后来我改成了更严格的Prompt你是一个严谨的问答助手。请严格根据以下参考内容回答问题。 如果参考内容中没有相关信息请直接说根据现有资料无法回答不要编造。 参考内容 {context} 问题{question} 回答要求 1. 只使用参考内容中的信息 2. 如果参考内容不足以回答明确说明 3. 回答要简洁不要重复参考内容加上不要编造和无法回答的指令之后幻觉问题明显减少了。但也不是100%能解决有些模型就是不听话这时候可以考虑换一个指令遵循能力更强的模型。5. 部署环节从本地跑通到稳定服务5.1 本地部署的硬件门槛我一开始想在自己的笔记本上跑本地模型结果发现12G显存跑7B的模型都很吃力。后来查了一下不同规模的模型对显存的要求大概是这样的模型规模FP16显存需求INT8量化INT4量化7B14GB7GB4GB13B26GB13GB7GB70B140GB70GB35GB我的RTX 3060 12G跑7B的INT4量化模型刚好够用但速度一般生成速度大概在10-20 token/s。如果要跑13B的模型就得用INT4量化而且速度会更慢。如果硬件条件有限我建议直接用API省心省力。本地部署适合对数据隐私要求高、或者需要离线运行的场景。5.2 Ollama本地部署实操Ollama是目前最简单的本地部署方案一条命令就能跑起来# 安装Ollama curl -fsSL https://ollama.com/install.sh | sh # 拉取模型 ollama pull qwen2:7b # 运行 ollama run qwen2:7bOllama默认的API端口是11434而且兼容OpenAI的接口格式所以之前写的API调用代码基本不用改只需要把URL换成http://localhost:11434/v1就行。但Ollama也有坑。第一个是模型下载慢有些模型在国内下载经常断。解决办法是配置镜像源或者手动下载模型文件再导入。第二个是默认的上下文长度比较小需要在Modelfile里手动设置FROM qwen2:7b PARAMETER num_ctx 8192这个num_ctx参数控制上下文窗口大小默认可能是2048或4096对于RAG场景来说不够用建议设成8192或更大。但注意上下文越长显存占用越大需要根据自己的硬件情况调整。5.3 RAG服务的API封装把RAG封装成API服务我用的是FastAPIfrom fastapi import FastAPI from pydantic import BaseModel app FastAPI() class QueryRequest(BaseModel): question: str top_k: int 5 class QueryResponse(BaseModel): answer: str sources: list app.post(/query, response_modelQueryResponse) async def query(request: QueryRequest): # 检索 docs vectorstore.similarity_search(request.question, krequest.top_k) context \n\n.join([d.page_content for d in docs]) # 生成 prompt f根据以下内容回答问题\n{context}\n\n问题{request.question} answer call_llm(prompt) return QueryResponse(answeranswer, sources[d.page_content[:100] for d in docs])这个服务跑起来之后前端或者其他系统就可以通过HTTP请求来调用RAG能力了。部署的时候我用的是uvicorn配合nginx做反向代理。5.4 性能优化缓存与并发RAG服务的响应时间主要花在两个地方检索和生成。检索一般很快几十毫秒生成取决于模型和硬件可能几秒到几十秒。优化的第一个手段是加缓存。相同的问题如果之前问过直接把缓存的结果返回from functools import lru_cache lru_cache(maxsize1000) def cached_query(question: str): # 检索和生成的逻辑 ...但要注意缓存key要包含top_k等参数不然不同参数的结果会混在一起。第二个手段是并发处理。FastAPI本身支持异步但调用大模型API是阻塞操作需要用run_in_executor包装import asyncio from concurrent.futures import ThreadPoolExecutor executor ThreadPoolExecutor(max_workers4) app.post(/query) async def query(request: QueryRequest): loop asyncio.get_event_loop() result await loop.run_in_executor(executor, sync_query, request) return result这样多个请求可以并行处理吞吐量能提升不少。但并发数不能设太大不然会把API限流或者把本地模型跑崩。6. 常见问题速查与避坑指南6.1 API调用类问题问题原因解决方案401 UnauthorizedKey错误或未激活检查Key格式用curl测试确认账户状态400 Context Length输入超过模型上限估算token数分段处理或上RAG429 Rate Limit请求频率过高加指数退避重试降低并发超时网络或服务端问题设置timeout加重试逻辑返回乱码编码问题确保请求和响应都用UTF-86.2 RAG类问题问题原因解决方案检索不到相关内容Embedding模型不匹配换中文优化的模型加指令前缀检索结果不相关切分粒度不合适调整chunk_size和overlap模型编造答案Prompt不够严格加不要编造指令设相似度阈值响应太慢检索或生成瓶颈加缓存优化Top-K换更快的模型显存不足模型太大或上下文太长用量化模型减小num_ctx6.3 我踩过的最大的三个坑第一个坑是Embedding模型和生成模型不匹配。我一开始用英文的Embedding模型处理中文文档检索出来的结果惨不忍睹。后来换成bge-small-zh效果立竿见影。这个教训是中文场景一定要用中文优化的Embedding模型。第二个坑是chunk_size设得太大。我一开始设了2000觉得这样上下文更完整。结果检索的时候一个块里包含了好几个主题模型经常抓错重点。后来改成500检索精准度提升了很多。第三个坑是忘了设num_ctx。Ollama默认的上下文长度只有2048我塞了3000字的context进去模型直接截断了回答驴唇不对马嘴。后来把num_ctx设成8192问题解决。6.4 给新手的路线建议如果你刚开始学大模型应用开发我建议按这个顺序来第一周先把API调用跑通。选一个便宜的API比如DeepSeek写几个简单的脚本熟悉请求格式、鉴权方式、错误处理。这个阶段不用追求复杂的功能能把发请求-收响应这个链路跑通就行。第二周练Prompt。拿几个实际的任务比如文本分类、信息抽取、摘要生成反复调整Prompt观察输出的变化。这个阶段的目标是建立起对Prompt的手感知道什么样的写法效果好、什么样的写法容易出问题。第三到四周上手RAG。先用LangChain或者LlamaIndex搭一个最简单的RAG跑通加载-切分-向量化-检索-生成的完整链路。然后逐步优化每个环节切分参数、Embedding模型、检索策略、Prompt设计一个一个调。第五周之后考虑部署。把RAG封装成API服务加上缓存和并发处理部署到服务器上。如果硬件允许可以试试本地模型如果不行就用API。整个路线走下来快的话一个月慢的话两三个月。关键是要动手做光看文档是学不会的。我踩过的这些坑你大概率也会踩但提前知道了至少能少走点弯路。最后分享一个我最近才发现的技巧在做RAG的时候检索出来的片段不要直接拼在一起而是按相似度排序后把最相关的放在最前面和最后面。因为大模型对开头和结尾的信息更敏感这样排列能提升回答的准确率。这个技巧是我在一次调试中偶然发现的后来查了一下确实有相关的研究支持。
1. 从API调用到RAG部署我踩过的那些坑去年年初我刚开始系统性地折腾大模型应用开发那时候手里就一个DeepSeek的API Key觉得调用大模型嘛无非就是发个HTTP请求、拿个返回结果能有多难。结果从第一个Demo跑通到后来把一套完整的RAG知识库部署上线中间踩的坑比我前三年写业务代码加起来都多。这篇文章不是教程是我自己复盘下来的踩坑记录把从API调用、Prompt设计、RAG搭建到最终部署这条链路上遇到的实际问题和解决思路都摊开讲一遍。如果你也是刚入门大模型应用开发或者已经能跑通简单的API调用但一到RAG就各种报错那这篇内容应该能帮你省下不少查文档和试错的时间。我会按学习路线的顺序来讲每个阶段说清楚三件事我当时怎么做的、遇到了什么问题、后来怎么解决的。涉及到的技术点包括API调用的鉴权与错误处理、Prompt工程的实际写法、RAG的检索与生成链路、以及本地化部署时的模型选型和资源配置。先说一下我的背景方便你对标。我有Python后端开发经验对Flask和FastAPI比较熟之前没接触过向量数据库和Embedding模型GPU资源只有一张RTX 3060 12G的卡。整个学习路线大概花了三个月前一个月在API调用和Prompt上反复折腾后两个月基本都在跟RAG的检索质量和部署环境较劲。2. API调用阶段那些让人抓狂的报错2.1 第一个401API Key的坑比想象中多我拿到的第一个API Key是DeepSeek的按照官方文档写了个最简单的Python脚本import requests url https://api.deepseek.com/v1/chat/completions headers { Authorization: Bearer sk-xxxxxxxxxxxxxxxx, Content-Type: application/json } data { model: deepseek-chat, messages: [{role: user, content: 你好}] } resp requests.post(url, headersheaders, jsondata) print(resp.json())跑出来直接报unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****。我当时第一反应是Key复制错了反复对了三遍确认没问题。后来才发现问题出在两个地方一是Key的前后可能有空格从网页复制的时候很容易带上二是有些平台的Key需要激活或者绑定支付方式之后才能用。提示拿到API Key之后先做一次最简单的curl测试排除代码层面的问题。如果curl也报401那就是Key本身的问题别在代码里浪费时间。排查401的步骤我后来总结成了一个固定流程先用curl直接测排除代码问题然后检查Key的格式确认没有多余空格和换行再确认账户状态有些平台新注册的Key需要等几分钟才生效最后看请求的URL是不是对的不同平台的endpoint路径不一样有的带/v1有的不带。2.2 400错误上下文长度超限的暴力解法有一次我往对话里塞了一篇很长的技术文档想让它帮我总结结果直接报api error: 400 this models maximum context length is 1048576 tokens。这个报错信息其实说得很清楚就是输入太长了。但问题是我怎么知道我的输入到底有多少token我的解决办法是装了一个tiktoken库来估算token数量import tiktoken def count_tokens(text, modelgpt-4): enc tiktoken.encoding_for_model(model) return len(enc.encode(text)) # 对于中文大概1个汉字约等于1.5-2个token text 你的长文本内容... print(f估算token数: {count_tokens(text)})但这里有个坑不同模型的tokenizer不一样tiktoken对OpenAI系列的模型比较准对国产模型的估算会有偏差。我后来养成的习惯是在发送请求之前先做一次长度检查如果超过模型上限的80%就先做一轮摘要或者分段处理。对于超长文本的处理我试过几种方案。最简单的是直接截断但会丢信息。稍微好一点的是分段摘要把长文档切成若干段每段单独摘要再把摘要拼起来。最靠谱的还是上RAG把文档存到向量数据库里需要的时候检索相关片段这样既不会超长又能保留关键信息。2.3 免费API的限流与重试策略刚开始学的时候我到处找免费的大模型API试过好几个平台。免费额度确实能用但限流很严重经常报429。我一开始没做重试程序直接崩了。后来加了一个简单的指数退避重试import time import requests def call_api_with_retry(url, headers, data, max_retries5): for attempt in range(max_retries): try: resp requests.post(url, headersheaders, jsondata, timeout30) if resp.status_code 429: wait 2 ** attempt print(f限流等待{wait}秒后重试) time.sleep(wait) continue return resp.json() except requests.exceptions.Timeout: print(f超时第{attempt1}次重试) time.sleep(2 ** attempt) raise Exception(重试次数用尽)这个重试逻辑后来成了我所有API调用代码的标配。另外还有一个经验免费API的响应时间波动很大有时候几秒有时候几十秒所以timeout一定要设不然程序会卡死。2.4 不同平台API的差异对比学路线中我陆续试了好几个平台的API包括DeepSeek、讯飞星火、以及通过OpenRouter调用的各种模型。每个平台的API格式都有差异这里整理一个对比平台鉴权方式请求格式特点DeepSeekBearer TokenOpenAI兼容便宜中文好推荐入门讯飞星火API Key Secret自有格式需要签名稍微复杂OpenRouterBearer TokenOpenAI兼容模型多但价格参差Ollama本地无OpenAI兼容免费但吃硬件我建议新手先从DeepSeek的API入手因为它的格式跟OpenAI完全兼容网上大部分教程都能直接套用。等你熟悉了基本的调用流程再去试其他平台。3. Prompt工程从瞎写到有章法3.1 我踩过的Prompt坑刚开始写Prompt的时候我就是直接把问题扔进去比如帮我写一个Python函数。结果出来的代码质量参差不齐有时候能跑有时候不能跑。后来我才意识到Prompt的质量直接决定了输出的质量。我遇到过一个很典型的问题就是Prompt被平台的安全审核拦截了报invalid prompt: your prompt was flagged as potentially violating our usage policy。那次是我在做一个文本分类的任务Prompt里包含了一些敏感词的示例结果被拦了。解决办法是把示例改成更中性的表述或者用占位符代替敏感内容。还有一个坑是Prompt太长导致模型忘记前面的指令。我试过写一个很长的System Prompt里面塞了十几条规则结果模型只记住了最后几条。后来我把规则精简到5条以内并且把最重要的规则放在最前面和最后面效果好了很多。3.2 结构化Prompt的写法经过反复试错我总结出了一个比较稳定的Prompt结构# 角色 你是一个资深的Python后端工程师擅长编写高质量、可维护的代码。 # 任务 根据用户的需求编写Python函数。 # 约束 1. 代码必须包含类型注解 2. 必须处理异常情况 3. 函数不超过50行 4. 添加简洁的注释 # 输出格式 直接输出代码不需要额外的解释。 # 用户需求 {user_input}这个结构的核心思路是把角色、任务、约束、输出格式分开写让模型能清晰地理解每个部分的要求。实测下来这种写法的输出稳定性比一大段自然语言描述要高不少。3.3 Few-shot示例的正确用法对于分类、抽取这类任务Few-shot示例的效果非常明显。但示例的选择有讲究我试过几种方案随机选示例效果一般有时候模型会学到错误的模式选最典型的示例效果好但需要人工挑选选边界情况的示例对提升模型的鲁棒性很有帮助我现在的做法是每个类别选2-3个示例其中至少有一个是边界情况。比如做一个情感分类的任务除了明显的正面和负面示例还会加一个中性偏正面的模糊示例这样模型对边界情况的判断会准很多。注意Few-shot示例不是越多越好。我试过放10个示例结果模型开始抄示例的输出格式反而忽略了实际输入。一般来说3-5个示例是比较合适的。3.4 Prompt版本管理这个是我踩了坑之后才养成的习惯。一开始我改Prompt就是直接在代码里改改完之后发现效果变差了想回退却找不到之前的版本。后来我把Prompt单独抽出来放在一个文件里用Git管理每次改动都写清楚改了什么、为什么改。# prompts/classify_v3.txt # 修改记录v3增加了边界情况的示例分类准确率从82%提升到89%这个习惯看起来简单但在后期调试的时候帮了我大忙。特别是做RAG的时候检索和生成两个环节的Prompt需要反复调整没有版本管理根本记不住哪个版本效果好。4. RAG实战从零搭一个能用的知识库4.1 RAG的基本链路RAG的核心思路其实不复杂把文档切成小块存到向量数据库里用户提问的时候先检索相关片段再把片段和问题一起发给大模型生成回答。但真正动手做的时候每个环节都有坑。我的第一条RAG链路是这样的from langchain.document_loaders import TextLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain.embeddings import HuggingFaceEmbeddings from langchain.vectorstores import Chroma # 1. 加载文档 loader TextLoader(knowledge.txt) docs loader.load() # 2. 切分文档 splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap50 ) chunks splitter.split_documents(docs) # 3. 向量化并存储 embeddings HuggingFaceEmbeddings(model_nameBAAI/bge-small-zh) vectorstore Chroma.from_documents(chunks, embeddings, persist_directory./db) # 4. 检索 results vectorstore.similarity_search(用户的问题, k3)这段代码看起来很简单但实际跑起来问题一堆。首先是Embedding模型下载慢HuggingFace的模型在国内下载经常超时。其次是切分参数不好定chunk_size设大了检索不精准设小了上下文不完整。4.2 文档切分最容易被忽视的关键环节文档切分是RAG里最不起眼但影响最大的环节。我一开始用固定长度切分500个字符一块结果经常把一句话切成两半检索出来的片段读都读不通。后来我改用了按语义切分优先在段落、句子边界处切分splitter RecursiveCharacterTextSplitter( chunk_size500, chunk_overlap100, separators[\n\n, \n, 。, , , , , , ] )separators的顺序很重要它会优先尝试用前面的分隔符切分。对于中文文档我把句号、问号、感叹号这些句子结束符放在前面这样切出来的块语义更完整。chunk_overlap也值得说一下。我一开始设的是0结果检索的时候经常漏掉跨块的信息。后来改成chunk_size的20%左右也就是100个字符效果好了很多。overlap的作用是让相邻的块之间有重叠这样即使关键信息刚好在边界上也能被检索到。4.3 Embedding模型选型中文场景的实测对比Embedding模型的选择直接决定了检索质量。我试过好几个模型这里把实测结果整理一下模型维度中文效果速度显存占用BAAI/bge-small-zh512不错快低BAAI/bge-base-zh768好中等中等BAAI/bge-large-zh1024很好慢高text-embedding-ada-0021536好快无API我的建议是如果显存有限比如只有8G用bge-small-zh就够了检索效果和large版本的差距没有想象中那么大。如果追求极致效果且显存充足bge-large-zh是更好的选择。用API的话OpenAI的text-embedding-ada-002很稳但需要付费。还有一个细节bge系列的模型在检索的时候需要加指令前缀。查询的时候加为这个句子生成表示以用于检索相关文章文档侧不加。这个细节官方文档里有写但很容易被忽略加上之后检索准确率能提升几个百分点。4.4 向量数据库选型Chroma vs Milvus vs FAISS向量数据库的选择我纠结了很久最后把三个主流的都试了一遍Chroma最大的优点是简单几行代码就能跑起来适合快速验证。但它的性能一般数据量大了之后检索会变慢。我试过存10万条数据检索延迟大概在200ms左右还能接受但再往上就不好说了。Milvus功能最全支持分布式部署性能也好。但部署复杂度高我用Docker Compose搭了一套光是配置文件就调了半天。如果你的数据量在百万级以上或者需要多用户并发访问Milvus是更好的选择。FAISS是Facebook开源的向量检索库性能很好但它是库不是服务需要自己封装成API。适合对性能要求高、且愿意自己写一层封装的场景。我最后选的是Chroma因为我的知识库规模不大几千条文档Chroma完全够用而且开发效率高。等数据量上来了再迁移到Milvus也不迟。4.5 检索策略优化从Top-K到混合检索基础的相似度检索有个问题就是有时候检索出来的片段跟问题语义相似但实际不相关。我试过几种优化方案第一种是调整Top-K。K太小会漏信息K太大又会引入噪声。我试了K3、5、10最后发现K5是个比较平衡的值。但K的值跟文档切分的粒度有关chunk_size小的时候K可以大一点反之则小一点。第二种是加相似度阈值。只保留相似度高于某个阈值的片段低于阈值的直接丢掉。这个阈值需要根据实际数据调我一般从0.7开始试。第三种是混合检索把向量检索和关键词检索结合起来。向量检索擅长语义匹配关键词检索擅长精确匹配两者互补。我用的是BM25做关键词检索然后跟向量检索的结果做加权融合def hybrid_search(query, vectorstore, bm25_index, alpha0.5, k5): # 向量检索 vector_results vectorstore.similarity_search_with_score(query, kk*2) # 关键词检索 bm25_results bm25_index.search(query, kk*2) # 融合排序 combined {} for doc, score in vector_results: combined[doc.page_content] alpha * (1 - score) for doc, score in bm25_results: if doc.page_content in combined: combined[doc.page_content] (1 - alpha) * score else: combined[doc.page_content] (1 - alpha) * score # 返回Top-K sorted_results sorted(combined.items(), keylambda x: x[1], reverseTrue) return sorted_results[:k]混合检索的效果确实比单一检索好但实现复杂度也上去了。我的建议是先把基础检索跑通遇到瓶颈了再考虑混合检索。4.6 RAG的Prompt设计检索到相关片段之后怎么把它们和问题一起发给大模型也是有讲究的。我一开始的Prompt是这样的根据以下内容回答问题 {context} 问题{question}结果模型经常编造答案明明context里没有的信息它也能编出来。后来我改成了更严格的Prompt你是一个严谨的问答助手。请严格根据以下参考内容回答问题。 如果参考内容中没有相关信息请直接说根据现有资料无法回答不要编造。 参考内容 {context} 问题{question} 回答要求 1. 只使用参考内容中的信息 2. 如果参考内容不足以回答明确说明 3. 回答要简洁不要重复参考内容加上不要编造和无法回答的指令之后幻觉问题明显减少了。但也不是100%能解决有些模型就是不听话这时候可以考虑换一个指令遵循能力更强的模型。5. 部署环节从本地跑通到稳定服务5.1 本地部署的硬件门槛我一开始想在自己的笔记本上跑本地模型结果发现12G显存跑7B的模型都很吃力。后来查了一下不同规模的模型对显存的要求大概是这样的模型规模FP16显存需求INT8量化INT4量化7B14GB7GB4GB13B26GB13GB7GB70B140GB70GB35GB我的RTX 3060 12G跑7B的INT4量化模型刚好够用但速度一般生成速度大概在10-20 token/s。如果要跑13B的模型就得用INT4量化而且速度会更慢。如果硬件条件有限我建议直接用API省心省力。本地部署适合对数据隐私要求高、或者需要离线运行的场景。5.2 Ollama本地部署实操Ollama是目前最简单的本地部署方案一条命令就能跑起来# 安装Ollama curl -fsSL https://ollama.com/install.sh | sh # 拉取模型 ollama pull qwen2:7b # 运行 ollama run qwen2:7bOllama默认的API端口是11434而且兼容OpenAI的接口格式所以之前写的API调用代码基本不用改只需要把URL换成http://localhost:11434/v1就行。但Ollama也有坑。第一个是模型下载慢有些模型在国内下载经常断。解决办法是配置镜像源或者手动下载模型文件再导入。第二个是默认的上下文长度比较小需要在Modelfile里手动设置FROM qwen2:7b PARAMETER num_ctx 8192这个num_ctx参数控制上下文窗口大小默认可能是2048或4096对于RAG场景来说不够用建议设成8192或更大。但注意上下文越长显存占用越大需要根据自己的硬件情况调整。5.3 RAG服务的API封装把RAG封装成API服务我用的是FastAPIfrom fastapi import FastAPI from pydantic import BaseModel app FastAPI() class QueryRequest(BaseModel): question: str top_k: int 5 class QueryResponse(BaseModel): answer: str sources: list app.post(/query, response_modelQueryResponse) async def query(request: QueryRequest): # 检索 docs vectorstore.similarity_search(request.question, krequest.top_k) context \n\n.join([d.page_content for d in docs]) # 生成 prompt f根据以下内容回答问题\n{context}\n\n问题{request.question} answer call_llm(prompt) return QueryResponse(answeranswer, sources[d.page_content[:100] for d in docs])这个服务跑起来之后前端或者其他系统就可以通过HTTP请求来调用RAG能力了。部署的时候我用的是uvicorn配合nginx做反向代理。5.4 性能优化缓存与并发RAG服务的响应时间主要花在两个地方检索和生成。检索一般很快几十毫秒生成取决于模型和硬件可能几秒到几十秒。优化的第一个手段是加缓存。相同的问题如果之前问过直接把缓存的结果返回from functools import lru_cache lru_cache(maxsize1000) def cached_query(question: str): # 检索和生成的逻辑 ...但要注意缓存key要包含top_k等参数不然不同参数的结果会混在一起。第二个手段是并发处理。FastAPI本身支持异步但调用大模型API是阻塞操作需要用run_in_executor包装import asyncio from concurrent.futures import ThreadPoolExecutor executor ThreadPoolExecutor(max_workers4) app.post(/query) async def query(request: QueryRequest): loop asyncio.get_event_loop() result await loop.run_in_executor(executor, sync_query, request) return result这样多个请求可以并行处理吞吐量能提升不少。但并发数不能设太大不然会把API限流或者把本地模型跑崩。6. 常见问题速查与避坑指南6.1 API调用类问题问题原因解决方案401 UnauthorizedKey错误或未激活检查Key格式用curl测试确认账户状态400 Context Length输入超过模型上限估算token数分段处理或上RAG429 Rate Limit请求频率过高加指数退避重试降低并发超时网络或服务端问题设置timeout加重试逻辑返回乱码编码问题确保请求和响应都用UTF-86.2 RAG类问题问题原因解决方案检索不到相关内容Embedding模型不匹配换中文优化的模型加指令前缀检索结果不相关切分粒度不合适调整chunk_size和overlap模型编造答案Prompt不够严格加不要编造指令设相似度阈值响应太慢检索或生成瓶颈加缓存优化Top-K换更快的模型显存不足模型太大或上下文太长用量化模型减小num_ctx6.3 我踩过的最大的三个坑第一个坑是Embedding模型和生成模型不匹配。我一开始用英文的Embedding模型处理中文文档检索出来的结果惨不忍睹。后来换成bge-small-zh效果立竿见影。这个教训是中文场景一定要用中文优化的Embedding模型。第二个坑是chunk_size设得太大。我一开始设了2000觉得这样上下文更完整。结果检索的时候一个块里包含了好几个主题模型经常抓错重点。后来改成500检索精准度提升了很多。第三个坑是忘了设num_ctx。Ollama默认的上下文长度只有2048我塞了3000字的context进去模型直接截断了回答驴唇不对马嘴。后来把num_ctx设成8192问题解决。6.4 给新手的路线建议如果你刚开始学大模型应用开发我建议按这个顺序来第一周先把API调用跑通。选一个便宜的API比如DeepSeek写几个简单的脚本熟悉请求格式、鉴权方式、错误处理。这个阶段不用追求复杂的功能能把发请求-收响应这个链路跑通就行。第二周练Prompt。拿几个实际的任务比如文本分类、信息抽取、摘要生成反复调整Prompt观察输出的变化。这个阶段的目标是建立起对Prompt的手感知道什么样的写法效果好、什么样的写法容易出问题。第三到四周上手RAG。先用LangChain或者LlamaIndex搭一个最简单的RAG跑通加载-切分-向量化-检索-生成的完整链路。然后逐步优化每个环节切分参数、Embedding模型、检索策略、Prompt设计一个一个调。第五周之后考虑部署。把RAG封装成API服务加上缓存和并发处理部署到服务器上。如果硬件允许可以试试本地模型如果不行就用API。整个路线走下来快的话一个月慢的话两三个月。关键是要动手做光看文档是学不会的。我踩过的这些坑你大概率也会踩但提前知道了至少能少走点弯路。最后分享一个我最近才发现的技巧在做RAG的时候检索出来的片段不要直接拼在一起而是按相似度排序后把最相关的放在最前面和最后面。因为大模型对开头和结尾的信息更敏感这样排列能提升回答的准确率。这个技巧是我在一次调试中偶然发现的后来查了一下确实有相关的研究支持。
