最近在负责一个 AI 应用项目时明显感觉到大模型相关的技术迭代节奏比以往任何一个技术栈都要快。今天刚做好的模型选型方案可能下周就被新发布的版本打破昨天还够用的上下文长度今天已经不够业务使用。这种快速变化给开发者带来的不只是兴奋更多是实打实的工程压力如何在大模型能力快速迭代的背景下做出稳定、可控、成本合理的应用方案。本文将围绕 AI 大模型应用开发这条主线梳理一套可以落地的工程实践方案。内容涵盖模型选型思路、API 接入方式、本地部署思路、Prompt 设计、AI Agent 工具调用、成本控制、模型评测和常见问题排查。无论你是刚接触 AI 开发的新手还是已经在业务中集成大模型的后端工程师都可以从这篇文章里找到可复用的内容。为了便于阅读本文先解释核心概念再给出环境准备和完整代码示例最后整理工程落地中的最佳实践和避坑清单。1. AI 大模型应用开发的背景与核心概念1.1 为什么大模型应用开发值得关注大模型Large Language ModelLLM本质上是一个通过海量文本数据训练出来的深度神经网络模型它能够根据用户输入的文本生成合理的、符合语境的后续内容。过去几年这类模型的发展速度非常快从早期的文本生成、文本分类到现在的多模态理解、代码生成、复杂推理能力边界在持续扩展。对于开发者来说大模型带来的最大变化并不是“能用自然语言写代码”而是把大量原本需要规则引擎、分类模型、人工审核才能实现的功能统一收敛到了“输入一段文本输出一段文本”的接口里。这种统一接口大大降低了自然语言处理任务的开发门槛。以前做一个客服问答系统需要分词、意图识别、实体抽取、检索排序、答案生成等多个模块配合现在用大模型可以直接把用户问题、知识库内容、对话历史一起交给模型由模型生成回答。但也正因为模型能力越来越强开发者在做技术选型时反而更难了。不同模型擅长领域不同参数量不同推理成本不同上下文窗口不同甚至同一个模型的不同版本行为也有差异。如果只是简单调用 API不考虑业务场景和成本约束很容易出现“功能能跑但运营成本居高不下”的尴尬局面。1.2 容易混淆的几个概念在阅读大模型相关技术文章时有几个概念经常被混用这里先做一个简单区分。大模型与基础模型大模型通常指参数量很大的神经网络模型基础模型Foundation Model更强调“可以适配多种下游任务”的通用性。在实际开发中这两个词往往指同一个东西但基础模型更强调“预训练 微调”的范式。API 调用与本地部署API 调用是指通过厂商提供的 HTTP 接口远程使用模型优势是接入快、无需 GPU 资源本地部署是指把模型权重下载到自己的服务器上运行优势是数据不出内网、推理成本可控制但需要准备 GPU 资源和推理框架。Prompt 与微调Prompt 是输入给模型的文本指令通过精心设计 Prompt 可以让模型按指定格式输出微调Fine-tuning是使用业务数据对模型参数进行二次训练。大多数场景先用 Prompt 解决只有 Prompt 无法满足需求时才考虑微调。RAG 与 AgentRAGRetrieval-Augmented Generation是“检索增强生成”先检索知识库中相关内容再让模型基于检索结果生成答案解决模型知识过期和幻觉问题Agent 则是在模型基础上加入规划、工具调用、记忆等能力让模型能完成多步任务。理解这些概念后再去看代码和配置就不会觉得混乱了。2. 环境准备与版本说明2.1 开发环境建议大模型应用开发以 Python 生态为主推荐使用 Python 3.10 及以上版本。原因在于新版 Python 对类型注解、异步编程的支持更好而主流的大模型 SDK 都已经适配了新版本。操作系统方面Windows、macOS、Linux 都可以作为开发环境。如果只做 API 调用普通开发机就够用如果要本地部署模型建议准备带有 NVIDIA GPU 的 Linux 服务器显存尽量在 16GB 以上否则只能跑中小尺寸模型。IDE 推荐使用 VS Code 或 PyCharm两个都可以。VS Code 配合 Python 插件比较轻量PyCharm 的项目管理功能更完整。以下示例不依赖特定 IDE命令行执行即可。2.2 Python 依赖安装本文示例主要用到两个库openai和python-dotenv。openai是官方 SDK支持 OpenAI 接口协议也可以用于接入兼容该协议的第三方模型服务python-dotenv用于读取.env配置文件避免把密钥硬编码在代码里。使用 pip 安装pip install openai python-dotenv如果你使用国内镜像源可以加快安装速度pip install openai python-dotenv -i https://pypi.tuna.tsinghua.edu.cn/simple需要注意的是大模型 SDK 版本更新很快不同版本的接口可能有细微差异。本文示例基于 openai 1.x 版本编写如果你的版本是 0.x接口写法会有所不同建议先升级到新版pip install --upgrade openai2.3 密钥管理规范调用大模型 API 需要填写 API Key。这里强烈建议不要将密钥直接写在代码中原因有两个一是代码可能被提交到 Git 仓库造成密钥泄露二是多人协作时不同人的密钥混杂在代码里很难管理。推荐的做法是创建.env文件把密钥放在里面同时把.env加入.gitignoretouch .env.env文件内容示例OPENAI_API_KEY你的API密钥 OPENAI_BASE_URLhttps://api.openai.com/v1 OPENAI_MODELgpt-4o-mini然后在 Python 代码中加载import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(OPENAI_API_KEY) base_url os.getenv(OPENAI_BASE_URL) model os.getenv(OPENAI_MODEL)如果使用的是国内模型服务OPENAI_BASE_URL需要替换为对应服务的地址。无论使用哪家模型管理密钥的思路都是一样的。3. 模型接入与基础调用3.1 API 调用最小示例先来看一个最简单的调用示例。这个示例的作用是向模型发送一条消息并打印返回结果# 文件路径demo_basic.py import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), ) response client.chat.completions.create( modelos.getenv(OPENAI_MODEL), messages[ {role: system, content: 你是一个专业的编程助手。}, {role: user, content: 请用一句话解释什么是大模型。}, ], temperature0.7, ) print(response.choices[0].message.content)运行命令python demo_basic.py这段代码中messages是核心参数。它包含两个角色system和user。system消息用于设定模型的角色和行为准则user消息用于传入用户的实际问题。这种消息结构是大模型对话接口的基础。temperature参数控制生成的随机性取值范围通常是 0 到 1 或 0 到 2不同厂商定义略有不同。值越小输出越稳定值越大输出越多样。在需要一致性输出的场景中建议把temperature调低例如 0.2 左右。3.2 流式输出与普通输出的区别上面示例是“一次性返回完整结果”也就是模型生成完毕后响应才返回给客户端。对于短回答这种模式足够使用。但如果模型要生成很长的内容用户需要等待较长时间体验较差。流式输出Streaming可以在模型逐字生成的同时把内容推送到客户端效果就像是 AI 打字机。实现方式如下# 文件路径demo_stream.py import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), ) stream client.chat.completions.create( modelos.getenv(OPENAI_MODEL), messages[ {role: user, content: 请写一段 200 字的短文介绍 Spring AI 的优势。}, ], streamTrue, ) for chunk in stream: if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end, flushTrue)流式输出在 Web 应用中通常配合 Server-Sent EventsSSE使用。后端把模型返回的每一个片段通过 SSE 推送给浏览器前端用EventSource或fetch读取并实时渲染。需要注意的是当streamTrue时响应对象不是完整的 Completion 对象而是一个迭代器。代码中需要逐个chunk处理取delta.content获取增量内容。3.3 本地模型部署思路API 调用虽然方便但有些业务场景对数据安全要求很高不允许把数据发送到外部服务。这时需要考虑本地模型部署。本地部署的核心思路是把开源模型权重下载到自己的服务器然后通过推理框架提供接口。常见的推理框架有 vLLM、Ollama、llama.cpp 等。Ollama 的安装和上手相对简单适合个人开发者和中小团队试用。以 Ollama 为例在 Linux 服务器上安装curl -fsSL https://ollama.com/install.sh | sh安装完成后拉取模型ollama pull qwen2.5:7b启动服务ollama serve之后可以通过本地接口调用模型curl http://localhost:11434/api/generate -d { model: qwen2.5:7b, prompt: 你好请介绍一下你自己 }本地部署虽然规避了数据外传问题但也带来了新的复杂度。首先是硬件成本7B 参数模型量化后大约需要 6GB 到 8GB 显存更大的模型需要更多显存其次是模型能力的取舍小尺寸模型在复杂推理任务上通常弱于大尺寸模型需要根据业务需求做权衡。3.4 Prompt 设计的基本原则Prompt 是调用大模型时最容易被忽略、也最影响效果的环节。同样的模型不同的 Prompt 设计输出质量可能相差很大。一个好的 Prompt 通常包含四个要素角色设定告诉模型以什么身份回答例如“你是一名资深 Java 工程师”。任务描述明确告诉模型要做什么例如“请审查以下代码指出潜在问题”。输入数据把需要处理的文本、代码、数据放入消息中。输出格式规定模型的输出结构例如“请用 Markdown 表格输出”“请只输出 JSON”。下面是一个相对完整的 Prompt 设计示例prompt f 你是一名数据分析助手。请根据以下用户反馈完成情感分类。 分类标准 - positive好评 - negative差评 - neutral中性 用户反馈 {user_feedback} 请只输出一个分类结果不要输出解释。 在这个示例中角色、任务、输入数据、输出格式都被明确定义了。这样设计的 Prompt 通常比“帮我分析一下这个评论是好评还是差评”稳定得多。Prompt 设计不是一次性工作需要根据模型的实际输出不断迭代。建议在开发阶段准备一套测试用例每次修改 Prompt 后都跑一遍对比输出效果。4. 完整实战构建一个 AI 资料问答助手4.1 需求分析前面了解了基础调用方式现在做一个完整的实战案例一个基于 RAG 思路的资料问答助手。用户可以向它提问它会先从本地资料库中检索相关内容再让模型基于检索结果回答。这个案例同时涉及三个关键技能知识库文本读取、文本向量检索、大模型生成。4.2 项目结构ai-qa-assistant/ ├── data/ │ └── knowledge.txt # 知识库文本 ├── .env # 环境变量 ├── .gitignore ├── requirements.txt ├── build_index.py # 索引构建脚本 └── query.py # 问答脚本4.3 知识库准备在data/knowledge.txt中放入一段业务资料这里以“Spring AI 常用概念”为例Spring AI 是 Spring 生态中面向 AI 应用开发的框架。 它的目标是把 AI 能力集成到 Spring Boot 应用中提供统一抽象。 Spring AI 支持多种模型供应商包括 OpenAI、Azure OpenAI、Ollama 等。 RAG 是 Retrieval-Augmented Generation 的缩写中文译为检索增强生成。 RAG 的核心思想是先检索外部知识再让大模型基于检索结果生成答案。 RAG 可以有效缓解大模型幻觉问题并让模型回答包含业务私域知识。 在 Spring AI 中VectorStore 是向量数据库的抽象接口。 常见的 VectorStore 实现包括 Redis、PGVector、Milvus 等。4.4 索引构建脚本为了让程序能检索知识库内容需要把文本切分成小块转换成语义向量然后存储到向量数据库中。为了减少依赖这里使用内存列表模拟向量存储并用一种简单的哈希特征算法生成固定长度的文本向量避免额外安装大型向量库。# 文件路径build_index.py import re import json import hashlib def load_text(file_path: str) - str: with open(file_path, r, encodingutf-8) as f: return f.read() def split_text(text: str, chunk_size: int 50) - list[str]: 按长度切分文本保留句子的完整性。 sentences re.split(r[。\n], text) chunks [] current for sentence in sentences: sentence sentence.strip() if not sentence: continue if len(current) len(sentence) chunk_size: current sentence 。 else: if current: chunks.append(current) current sentence 。 if current: chunks.append(current) return chunks def text_to_vector(text: str, dimension: int 64) - list[float]: 基于哈希生成固定维度向量用于演示检索效果。 vector [0.0] * dimension tokens re.findall(r[\w\u4e00-\u9fff], text) for token in tokens: digest hashlib.md5(token.encode(utf-8)).hexdigest() index int(digest[:8], 16) % dimension vector[index] 1.0 norm sum(x * x for x in vector) ** 0.5 if norm 0: vector [x / norm for x in vector] return vector def save_index(chunks: list[str], vectors: list[list[float]]): data { chunks: chunks, vectors: vectors, } with open(index.json, w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse) if __name__ __main__: text load_text(data/knowledge.txt) chunks split_text(text, chunk_size50) vectors [text_to_vector(chunk) for chunk in chunks] save_index(chunks, vectors) print(f索引构建完成共 {len(chunks)} 个文本块。) for idx, chunk in enumerate(chunks): print(f块 {idx}: {chunk})这里split_text把知识库文本按句子边界切分成小块text_to_vector使用哈希特征生成向量目的是演示检索流程。在实际项目中这个步骤通常替换为 Embedding API 或本地嵌入模型向量维度根据模型而定常见的有 768、1024、1536 等。4.5 问答脚本索引构建完成后编写问答脚本。查询时先计算用户问题的向量然后和索引中的向量做余弦相似度计算找出最相关的文本块最后把相关文本块拼接到 Prompt 中让模型生成答案。# 文件路径query.py import os import json import hashlib import re from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), ) def load_index(): with open(index.json, r, encodingutf-8) as f: data json.load(f) return data[chunks], data[vectors] def text_to_vector(text: str, dimension: int 64) - list[float]: tokens re.findall(r[\w\u4e00-\u9fff], text) vector [0.0] * dimension for token in tokens: digest hashlib.md5(token.encode(utf-8)).hexdigest() index int(digest[:8], 16) % dimension vector[index] 1.0 norm sum(x * x for x in vector) ** 0.5 if norm 0: vector [x / norm for x in vector] return vector def cosine_similarity(vec_a: list[float], vec_b: list[float]) - float: return sum(x * y for x, y in zip(vec_a, vec_b)) def search_chunks(query: str, chunks: list[str], vectors: list[list[float]], top_k: int 2): query_vector text_to_vector(query) scored [] for i, vector in enumerate(vectors): score cosine_similarity(query_vector, vector) scored.append((score, i)) scored.sort(reverseTrue) results [(chunks[i], score) for score, i in scored[:top_k]] return results def generate_answer(question: str, contexts: list[str]) - str: context_text \n.join(contexts) messages [ { role: system, content: 你是一个严谨的问答助手。请只根据提供的资料回答问题如果资料中没有相关内容请明确回答不知道。, }, { role: user, content: f资料如下\n{context_text}\n\n问题{question}, }, ] response client.chat.completions.create( modelos.getenv(OPENAI_MODEL), messagesmessages, temperature0.2, ) return response.choices[0].message.content if __name__ __main__: chunks, vectors load_index() while True: question input(请输入问题输入 exit 退出).strip() if question.lower() exit: break results search_chunks(question, chunks, vectors, top_k2) print(\n--- 检索结果 ---) for idx, (chunk, score) in enumerate(results): print(f候选 {idx 1} (相似度 {score:.4f}): {chunk}) answer generate_answer(question, [chunk for chunk, _ in results]) print(\n--- 回答 ---) print(answer) print()运行问答脚本python query.py4.6 验证效果运行脚本后输入问题“什么是 RAG”系统会先输出检索到的文本块再输出模型生成的答案。如果知识库中的文本块包含了 RAG 的定义那么检索结果会返回相关文本块模型会基于这些文本块生成回答请输入问题输入 exit 退出什么是 RAG --- 检索结果 --- 候选 1 (相似度 0.31): RAG 是 Retrieval-Augmented Generation 的缩写中文译为检索增强生成。。 候选 2 (相似度 0.20): RAG 的核心思想是先检索外部知识再让大模型基于检索结果生成答案。。 ...如果模型 API 配置正确回答会基于资料内容生成。这验证了 RAG 的基本流程检索、拼接、生成。需要说明的是这里使用的哈希向量只适合演示流程实际项目中应使用语义向量模型例如 OpenAI Embedding、BGE、M3E 等。语义向量对同义词和语义相近的句子有更好的检索效果。5. AI Agent 与工具调用5.1 Agent 解决什么问题RAG 解决了“模型不知道私域知识”的问题但如果任务要求模型完成多步操作例如查询天气、调用数据库、发送邮件仅靠对话生成就不够了。这时需要 Agent 能力。Agent 的核心机制是 Function Calling函数调用。模型在生成回答时可以输出结构化指令表示“我需要调用某个函数”而不是直接生成普通文本。应用收到指令后执行对应的函数把执行结果返回给模型模型再根据结果继续生成最终回答。这个机制让大模型从“文本生成器”变成了“任务调度器”。它可以自主决定调用哪个工具、传什么参数、根据工具结果决定下一步动作。5.2 Function Calling 最小示例假设我们有一个获取城市天气的函数希望让模型根据用户问题自动判断是否需要调用该函数。首先定义函数def get_weather(city: str) - str: 模拟获取天气信息实际项目中可以替换为真实天气 API。 weather_map { 北京: 晴25°C, 上海: 多云28°C, 广州: 小雨30°C, } return weather_map.get(city, 暂不支持该城市天气查询)然后调用 Chat Completions 接口并把tools参数传入# 文件路径demo_function_call.py import os import json from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), ) def get_weather(city: str) - str: weather_map { 北京: 晴25°C, 上海: 多云28°C, 广州: 小雨30°C, } return weather_map.get(city, 暂不支持该城市天气查询) messages [ {role: user, content: 北京今天天气怎么样}, ] tools [ { type: function, function: { name: get_weather, description: 查询指定城市今天的天气情况, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如北京, } }, required: [city], }, }, } ] response client.chat.completions.create( modelos.getenv(OPENAI_MODEL), messagesmessages, toolstools, tool_choiceauto, ) message response.choices[0].message print(模型返回内容, message.content) print(工具调用, message.tool_calls) if message.tool_calls: for tool_call in message.tool_calls: name tool_call.function.name arguments json.loads(tool_call.function.arguments) if name get_weather: result get_weather(cityarguments[city]) messages.append(message) messages.append({ role: tool, tool_call_id: tool_call.id, content: str(result), }) second_response client.chat.completions.create( modelos.getenv(OPENAI_MODEL), messagesmessages, toolstools, ) print(最终回答, second_response.choices[0].message.content)5.3 Agent 工程化的注意事项Function Calling 在示例中看起来很简单但工程化落地时需要注意几个问题。第一工具描述要详细。模型的函数调用判断依赖description字段描述越清晰调用准确率越高。第二参数校验不能省。模型返回的参数格式虽然遵循 JSON Schema但仍可能缺少必填字段或者参数值不在预期范围内执行函数前必须校验。第三要考虑多轮调用的上限。一个复杂 Agent 任务可能需要多次调用工具开发时需要设置最大轮数防止死循环和成本失控。实际项目中Agent 还可以接入记忆模块把历史对话和已执行的操作记录下来帮助模型在长任务中保持状态。但记忆模块会增加系统复杂度建议先从简单的单工具调用开始逐步增加能力。6. 常见问题与排查思路6.1 API 返回错误问题现象常见原因解决思路AuthenticationErrorAPI Key 填错或已过期检查.env文件中的密钥确认没有空格NotFoundError模型名称不存在或账号无权访问该模型确认模型标识是否正确检查服务商的模型列表RateLimitError请求频率超出限制增加重试机制考虑降低并发或联系服务商提高限额APIConnectionError网络无法连接到模型服务检查网络、代理设置确认 base_url 是否正确ContextLengthExceeded输入消息超过模型上下文窗口精简 Prompt或对历史消息做截断和摘要6.2 输出质量不稳定模型输出不稳定是一个高频问题尤其是同一个 Prompt 在不同时间得到不同结果。排查时先看temperature参数如果设置过高模型输出随机性会明显增强。其次是 Prompt 是否足够明确输出格式是否做了硬性约束。还可以尝试在 Prompt 末尾增加“请确认你的回答符合上述要求”这类提示有时能提升输出稳定性。更系统的方法是建立评估集。准备 20 到 50 个测试问题以及对应的期望回答标准每次修改 Prompt 或更换模型时运行一轮评估对比输出质量。不要凭一两次测试的结果判断模型好坏。6.3 本地部署推理缓慢本地模型推理速度慢通常与硬件和推理框架选择有关。显存不足时模型会使用 CPU 或内存做部分计算速度会大幅下降。解决方案包括使用量化模型减少显存占用例如 4bit 量化选择推理效率更高的框架例如 vLLM在推理服务中开启动态批处理提高 GPU 利用率。如果显存和性能仍然不够建议回到 API 调用方案或者使用更小的模型版本。6.4 检索不到相关内容RAG 项目中最常见的现象是知识库里明明有答案但模型就是回答不出来。排查时先检查文本切分粒度。如果文本块太小单块包含的信息有限如果文本块太大超过模型上下文窗口检索精度也会下降。其次是嵌入模型的质量哈希向量和简单的嵌入模型对语义理解有限建议换成更专业的 Embedding 模型。可以打印检索命中的文本块查看命中的内容是否真的包含问题答案。如果检索结果本身就不相关问题出在检索环节如果检索结果相关但回答错误问题出在 Prompt 或大模型环节。6.5 安全与合规风险大模型应用上线前必须做安全审查。尤其是面向外部用户的产品要防止 Prompt 注入、敏感信息泄露、生成违规内容等风险。建议在系统层面对输入输出做内容和关键词审核对模型返回结果进行二次过滤。涉及用户数据和业务数据时严格遵守最小权限原则只把必要的数据传给模型。如果业务涉及生产环境和真实数据所有变更都要先在测试环境验证做好备份和回滚方案避免出现数据丢失或不可恢复的问题。7. 最佳实践与工程建议7.1 模型选型要结合成本与效果大模型选型不能只看跑分要结合业务场景、数据规模、调用频率、预算和响应速度综合判断。对于那些需要处理大量简单文本的场景选择小尺寸模型即可成本低、响应快对于复杂推理、代码生成、长文本理解场景再考虑大尺寸模型。建议在项目初期同时接入多个模型供应商通过统一的封装层隔离差异。这样既可以在不同模型之间做 A/B 测试也可以在某一家服务不稳定时快速切换降低供应商锁定风险。7.2 把 Prompt 当作代码管理Prompt 不是“一次性写好的提示语”而是需要版本管理的应用资产。建议把实际业务中使用的 Prompt 写在单独的配置文件中使用 Prompts 文件管理。修改 Prompt 时遵循代码评审流程记录每次变更的原因。项目目录中可以单独建一个prompts文件夹按业务功能划分文件。同一个 Prompt 模板要避免在多个 Python 文件中重复复制。否则修改一处其他位置的 Prompt 还是旧版本排查起来非常麻烦。7.3 建立模型输出缓存大模型 API 调用有延迟费用也不便宜。对于相同问题、相同参数、相同上下文的重复请求可以使用缓存层直接返回结果减少 API 调用次数。缓存键可以设计为“模型名称 Prompt 用户输入 主要参数”的哈希值缓存的过期时间根据业务需求设置。注意涉及实时数据的场景不要使用长时间缓存。7.4 日志与可观测性大模型应用的可观测性比传统应用更复杂因为同一个 Prompt 可能产生不同输出。建议在日志中记录以下字段请求时间、用户标识、会话标识模型名称、版本、temperature 等参数输入消息摘要和输出消息摘要Token 使用量、响应耗时是否触发工具调用、调用了哪些工具错误信息和重试次数有了这些日志才能在线上问题出现时回溯分析判断是模型问题、参数问题还是业务逻辑问题。7.5 安全边界与数据隐私在 AI 应用中数据隐私是绝对不能忽视的问题。把数据发送给外部模型服务前要明确数据中是否包含敏感信息。对敏感字段做脱敏处理后再调用模型。如果使用外部模型服务有合规风险考虑本地部署方案确保数据不出内网。同时要防止 Prompt 注入攻击。例如知识库内容可能被恶意构造让模型忽略原有指令。开发时应对知识库内容进行来源审查并对模型输出中的异常指令保持警惕。7.6 从 API 到生产的落地顺序建议遵循“Prompt → RAG → Fine-tuning → 本地部署”的演进路径。先通过优化 Prompt 解决大部分问题再引入 RAG 解决私域知识问题仍然不满足需求时考虑微调。本地部署放在最后因为它涉及 GPU 资源、推理框架和运维成本没有充分的理由不要轻易上。每一步都做好测试和评估不要为了追求“更高级”的方案而增加不必要的复杂度。一个大模型应用项目是否成功最终要看业务效果是否提升而不是用了多复杂的模型。8. 总结与下一步学习建议本文从大模型应用开发的背景出发逐步介绍了模型选型、API 调用、流式输出、本地部署思路、Prompt 设计、RAG 问答助手、Function Calling 和 Agent 工程化。通过完整案例演示了如何读取知识库、构建索引、检索文本块、调用大模型生成答案并整理了常见的错误排查方法和工程建议。如果这是你接触大模型开发的第一篇文章建议先把第 3 章的 API 调用示例跑通再动手实践第 4 章的问答助手。过程中遇到报错不要慌先确认环境变量是否正确、模型名称是否有效、网络是否能连通再逐步排查代码逻辑。下一步可以从三个方向继续深入一是学习如何使用真正的 Embedding 模型和向量数据库如 PGVector、Milvus、Redis Search把 RAG 案例升级为生产级实现二是研究 Spring AI 或 LangChain 这类框架的源码和设计思路理解工具调用、Agent 编排的抽象方式三是关注模型评测和成本优化建立一套属于自己团队的模型评估体系。大模型技术迭代很快今天的最佳实践可能很快就会过时。但只要掌握了“概念理解 → 环境验证 → 最小实现 → 工程化打磨”这套方法无论技术怎么变你都能快速上手。动手写代码永远是最好的学习方式。 大模型应用开发实战：从API调用到RAG与Agent工程化
最近在负责一个 AI 应用项目时明显感觉到大模型相关的技术迭代节奏比以往任何一个技术栈都要快。今天刚做好的模型选型方案可能下周就被新发布的版本打破昨天还够用的上下文长度今天已经不够业务使用。这种快速变化给开发者带来的不只是兴奋更多是实打实的工程压力如何在大模型能力快速迭代的背景下做出稳定、可控、成本合理的应用方案。本文将围绕 AI 大模型应用开发这条主线梳理一套可以落地的工程实践方案。内容涵盖模型选型思路、API 接入方式、本地部署思路、Prompt 设计、AI Agent 工具调用、成本控制、模型评测和常见问题排查。无论你是刚接触 AI 开发的新手还是已经在业务中集成大模型的后端工程师都可以从这篇文章里找到可复用的内容。为了便于阅读本文先解释核心概念再给出环境准备和完整代码示例最后整理工程落地中的最佳实践和避坑清单。1. AI 大模型应用开发的背景与核心概念1.1 为什么大模型应用开发值得关注大模型Large Language ModelLLM本质上是一个通过海量文本数据训练出来的深度神经网络模型它能够根据用户输入的文本生成合理的、符合语境的后续内容。过去几年这类模型的发展速度非常快从早期的文本生成、文本分类到现在的多模态理解、代码生成、复杂推理能力边界在持续扩展。对于开发者来说大模型带来的最大变化并不是“能用自然语言写代码”而是把大量原本需要规则引擎、分类模型、人工审核才能实现的功能统一收敛到了“输入一段文本输出一段文本”的接口里。这种统一接口大大降低了自然语言处理任务的开发门槛。以前做一个客服问答系统需要分词、意图识别、实体抽取、检索排序、答案生成等多个模块配合现在用大模型可以直接把用户问题、知识库内容、对话历史一起交给模型由模型生成回答。但也正因为模型能力越来越强开发者在做技术选型时反而更难了。不同模型擅长领域不同参数量不同推理成本不同上下文窗口不同甚至同一个模型的不同版本行为也有差异。如果只是简单调用 API不考虑业务场景和成本约束很容易出现“功能能跑但运营成本居高不下”的尴尬局面。1.2 容易混淆的几个概念在阅读大模型相关技术文章时有几个概念经常被混用这里先做一个简单区分。大模型与基础模型大模型通常指参数量很大的神经网络模型基础模型Foundation Model更强调“可以适配多种下游任务”的通用性。在实际开发中这两个词往往指同一个东西但基础模型更强调“预训练 微调”的范式。API 调用与本地部署API 调用是指通过厂商提供的 HTTP 接口远程使用模型优势是接入快、无需 GPU 资源本地部署是指把模型权重下载到自己的服务器上运行优势是数据不出内网、推理成本可控制但需要准备 GPU 资源和推理框架。Prompt 与微调Prompt 是输入给模型的文本指令通过精心设计 Prompt 可以让模型按指定格式输出微调Fine-tuning是使用业务数据对模型参数进行二次训练。大多数场景先用 Prompt 解决只有 Prompt 无法满足需求时才考虑微调。RAG 与 AgentRAGRetrieval-Augmented Generation是“检索增强生成”先检索知识库中相关内容再让模型基于检索结果生成答案解决模型知识过期和幻觉问题Agent 则是在模型基础上加入规划、工具调用、记忆等能力让模型能完成多步任务。理解这些概念后再去看代码和配置就不会觉得混乱了。2. 环境准备与版本说明2.1 开发环境建议大模型应用开发以 Python 生态为主推荐使用 Python 3.10 及以上版本。原因在于新版 Python 对类型注解、异步编程的支持更好而主流的大模型 SDK 都已经适配了新版本。操作系统方面Windows、macOS、Linux 都可以作为开发环境。如果只做 API 调用普通开发机就够用如果要本地部署模型建议准备带有 NVIDIA GPU 的 Linux 服务器显存尽量在 16GB 以上否则只能跑中小尺寸模型。IDE 推荐使用 VS Code 或 PyCharm两个都可以。VS Code 配合 Python 插件比较轻量PyCharm 的项目管理功能更完整。以下示例不依赖特定 IDE命令行执行即可。2.2 Python 依赖安装本文示例主要用到两个库openai和python-dotenv。openai是官方 SDK支持 OpenAI 接口协议也可以用于接入兼容该协议的第三方模型服务python-dotenv用于读取.env配置文件避免把密钥硬编码在代码里。使用 pip 安装pip install openai python-dotenv如果你使用国内镜像源可以加快安装速度pip install openai python-dotenv -i https://pypi.tuna.tsinghua.edu.cn/simple需要注意的是大模型 SDK 版本更新很快不同版本的接口可能有细微差异。本文示例基于 openai 1.x 版本编写如果你的版本是 0.x接口写法会有所不同建议先升级到新版pip install --upgrade openai2.3 密钥管理规范调用大模型 API 需要填写 API Key。这里强烈建议不要将密钥直接写在代码中原因有两个一是代码可能被提交到 Git 仓库造成密钥泄露二是多人协作时不同人的密钥混杂在代码里很难管理。推荐的做法是创建.env文件把密钥放在里面同时把.env加入.gitignoretouch .env.env文件内容示例OPENAI_API_KEY你的API密钥 OPENAI_BASE_URLhttps://api.openai.com/v1 OPENAI_MODELgpt-4o-mini然后在 Python 代码中加载import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(OPENAI_API_KEY) base_url os.getenv(OPENAI_BASE_URL) model os.getenv(OPENAI_MODEL)如果使用的是国内模型服务OPENAI_BASE_URL需要替换为对应服务的地址。无论使用哪家模型管理密钥的思路都是一样的。3. 模型接入与基础调用3.1 API 调用最小示例先来看一个最简单的调用示例。这个示例的作用是向模型发送一条消息并打印返回结果# 文件路径demo_basic.py import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), ) response client.chat.completions.create( modelos.getenv(OPENAI_MODEL), messages[ {role: system, content: 你是一个专业的编程助手。}, {role: user, content: 请用一句话解释什么是大模型。}, ], temperature0.7, ) print(response.choices[0].message.content)运行命令python demo_basic.py这段代码中messages是核心参数。它包含两个角色system和user。system消息用于设定模型的角色和行为准则user消息用于传入用户的实际问题。这种消息结构是大模型对话接口的基础。temperature参数控制生成的随机性取值范围通常是 0 到 1 或 0 到 2不同厂商定义略有不同。值越小输出越稳定值越大输出越多样。在需要一致性输出的场景中建议把temperature调低例如 0.2 左右。3.2 流式输出与普通输出的区别上面示例是“一次性返回完整结果”也就是模型生成完毕后响应才返回给客户端。对于短回答这种模式足够使用。但如果模型要生成很长的内容用户需要等待较长时间体验较差。流式输出Streaming可以在模型逐字生成的同时把内容推送到客户端效果就像是 AI 打字机。实现方式如下# 文件路径demo_stream.py import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), ) stream client.chat.completions.create( modelos.getenv(OPENAI_MODEL), messages[ {role: user, content: 请写一段 200 字的短文介绍 Spring AI 的优势。}, ], streamTrue, ) for chunk in stream: if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end, flushTrue)流式输出在 Web 应用中通常配合 Server-Sent EventsSSE使用。后端把模型返回的每一个片段通过 SSE 推送给浏览器前端用EventSource或fetch读取并实时渲染。需要注意的是当streamTrue时响应对象不是完整的 Completion 对象而是一个迭代器。代码中需要逐个chunk处理取delta.content获取增量内容。3.3 本地模型部署思路API 调用虽然方便但有些业务场景对数据安全要求很高不允许把数据发送到外部服务。这时需要考虑本地模型部署。本地部署的核心思路是把开源模型权重下载到自己的服务器然后通过推理框架提供接口。常见的推理框架有 vLLM、Ollama、llama.cpp 等。Ollama 的安装和上手相对简单适合个人开发者和中小团队试用。以 Ollama 为例在 Linux 服务器上安装curl -fsSL https://ollama.com/install.sh | sh安装完成后拉取模型ollama pull qwen2.5:7b启动服务ollama serve之后可以通过本地接口调用模型curl http://localhost:11434/api/generate -d { model: qwen2.5:7b, prompt: 你好请介绍一下你自己 }本地部署虽然规避了数据外传问题但也带来了新的复杂度。首先是硬件成本7B 参数模型量化后大约需要 6GB 到 8GB 显存更大的模型需要更多显存其次是模型能力的取舍小尺寸模型在复杂推理任务上通常弱于大尺寸模型需要根据业务需求做权衡。3.4 Prompt 设计的基本原则Prompt 是调用大模型时最容易被忽略、也最影响效果的环节。同样的模型不同的 Prompt 设计输出质量可能相差很大。一个好的 Prompt 通常包含四个要素角色设定告诉模型以什么身份回答例如“你是一名资深 Java 工程师”。任务描述明确告诉模型要做什么例如“请审查以下代码指出潜在问题”。输入数据把需要处理的文本、代码、数据放入消息中。输出格式规定模型的输出结构例如“请用 Markdown 表格输出”“请只输出 JSON”。下面是一个相对完整的 Prompt 设计示例prompt f 你是一名数据分析助手。请根据以下用户反馈完成情感分类。 分类标准 - positive好评 - negative差评 - neutral中性 用户反馈 {user_feedback} 请只输出一个分类结果不要输出解释。 在这个示例中角色、任务、输入数据、输出格式都被明确定义了。这样设计的 Prompt 通常比“帮我分析一下这个评论是好评还是差评”稳定得多。Prompt 设计不是一次性工作需要根据模型的实际输出不断迭代。建议在开发阶段准备一套测试用例每次修改 Prompt 后都跑一遍对比输出效果。4. 完整实战构建一个 AI 资料问答助手4.1 需求分析前面了解了基础调用方式现在做一个完整的实战案例一个基于 RAG 思路的资料问答助手。用户可以向它提问它会先从本地资料库中检索相关内容再让模型基于检索结果回答。这个案例同时涉及三个关键技能知识库文本读取、文本向量检索、大模型生成。4.2 项目结构ai-qa-assistant/ ├── data/ │ └── knowledge.txt # 知识库文本 ├── .env # 环境变量 ├── .gitignore ├── requirements.txt ├── build_index.py # 索引构建脚本 └── query.py # 问答脚本4.3 知识库准备在data/knowledge.txt中放入一段业务资料这里以“Spring AI 常用概念”为例Spring AI 是 Spring 生态中面向 AI 应用开发的框架。 它的目标是把 AI 能力集成到 Spring Boot 应用中提供统一抽象。 Spring AI 支持多种模型供应商包括 OpenAI、Azure OpenAI、Ollama 等。 RAG 是 Retrieval-Augmented Generation 的缩写中文译为检索增强生成。 RAG 的核心思想是先检索外部知识再让大模型基于检索结果生成答案。 RAG 可以有效缓解大模型幻觉问题并让模型回答包含业务私域知识。 在 Spring AI 中VectorStore 是向量数据库的抽象接口。 常见的 VectorStore 实现包括 Redis、PGVector、Milvus 等。4.4 索引构建脚本为了让程序能检索知识库内容需要把文本切分成小块转换成语义向量然后存储到向量数据库中。为了减少依赖这里使用内存列表模拟向量存储并用一种简单的哈希特征算法生成固定长度的文本向量避免额外安装大型向量库。# 文件路径build_index.py import re import json import hashlib def load_text(file_path: str) - str: with open(file_path, r, encodingutf-8) as f: return f.read() def split_text(text: str, chunk_size: int 50) - list[str]: 按长度切分文本保留句子的完整性。 sentences re.split(r[。\n], text) chunks [] current for sentence in sentences: sentence sentence.strip() if not sentence: continue if len(current) len(sentence) chunk_size: current sentence 。 else: if current: chunks.append(current) current sentence 。 if current: chunks.append(current) return chunks def text_to_vector(text: str, dimension: int 64) - list[float]: 基于哈希生成固定维度向量用于演示检索效果。 vector [0.0] * dimension tokens re.findall(r[\w\u4e00-\u9fff], text) for token in tokens: digest hashlib.md5(token.encode(utf-8)).hexdigest() index int(digest[:8], 16) % dimension vector[index] 1.0 norm sum(x * x for x in vector) ** 0.5 if norm 0: vector [x / norm for x in vector] return vector def save_index(chunks: list[str], vectors: list[list[float]]): data { chunks: chunks, vectors: vectors, } with open(index.json, w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse) if __name__ __main__: text load_text(data/knowledge.txt) chunks split_text(text, chunk_size50) vectors [text_to_vector(chunk) for chunk in chunks] save_index(chunks, vectors) print(f索引构建完成共 {len(chunks)} 个文本块。) for idx, chunk in enumerate(chunks): print(f块 {idx}: {chunk})这里split_text把知识库文本按句子边界切分成小块text_to_vector使用哈希特征生成向量目的是演示检索流程。在实际项目中这个步骤通常替换为 Embedding API 或本地嵌入模型向量维度根据模型而定常见的有 768、1024、1536 等。4.5 问答脚本索引构建完成后编写问答脚本。查询时先计算用户问题的向量然后和索引中的向量做余弦相似度计算找出最相关的文本块最后把相关文本块拼接到 Prompt 中让模型生成答案。# 文件路径query.py import os import json import hashlib import re from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), ) def load_index(): with open(index.json, r, encodingutf-8) as f: data json.load(f) return data[chunks], data[vectors] def text_to_vector(text: str, dimension: int 64) - list[float]: tokens re.findall(r[\w\u4e00-\u9fff], text) vector [0.0] * dimension for token in tokens: digest hashlib.md5(token.encode(utf-8)).hexdigest() index int(digest[:8], 16) % dimension vector[index] 1.0 norm sum(x * x for x in vector) ** 0.5 if norm 0: vector [x / norm for x in vector] return vector def cosine_similarity(vec_a: list[float], vec_b: list[float]) - float: return sum(x * y for x, y in zip(vec_a, vec_b)) def search_chunks(query: str, chunks: list[str], vectors: list[list[float]], top_k: int 2): query_vector text_to_vector(query) scored [] for i, vector in enumerate(vectors): score cosine_similarity(query_vector, vector) scored.append((score, i)) scored.sort(reverseTrue) results [(chunks[i], score) for score, i in scored[:top_k]] return results def generate_answer(question: str, contexts: list[str]) - str: context_text \n.join(contexts) messages [ { role: system, content: 你是一个严谨的问答助手。请只根据提供的资料回答问题如果资料中没有相关内容请明确回答不知道。, }, { role: user, content: f资料如下\n{context_text}\n\n问题{question}, }, ] response client.chat.completions.create( modelos.getenv(OPENAI_MODEL), messagesmessages, temperature0.2, ) return response.choices[0].message.content if __name__ __main__: chunks, vectors load_index() while True: question input(请输入问题输入 exit 退出).strip() if question.lower() exit: break results search_chunks(question, chunks, vectors, top_k2) print(\n--- 检索结果 ---) for idx, (chunk, score) in enumerate(results): print(f候选 {idx 1} (相似度 {score:.4f}): {chunk}) answer generate_answer(question, [chunk for chunk, _ in results]) print(\n--- 回答 ---) print(answer) print()运行问答脚本python query.py4.6 验证效果运行脚本后输入问题“什么是 RAG”系统会先输出检索到的文本块再输出模型生成的答案。如果知识库中的文本块包含了 RAG 的定义那么检索结果会返回相关文本块模型会基于这些文本块生成回答请输入问题输入 exit 退出什么是 RAG --- 检索结果 --- 候选 1 (相似度 0.31): RAG 是 Retrieval-Augmented Generation 的缩写中文译为检索增强生成。。 候选 2 (相似度 0.20): RAG 的核心思想是先检索外部知识再让大模型基于检索结果生成答案。。 ...如果模型 API 配置正确回答会基于资料内容生成。这验证了 RAG 的基本流程检索、拼接、生成。需要说明的是这里使用的哈希向量只适合演示流程实际项目中应使用语义向量模型例如 OpenAI Embedding、BGE、M3E 等。语义向量对同义词和语义相近的句子有更好的检索效果。5. AI Agent 与工具调用5.1 Agent 解决什么问题RAG 解决了“模型不知道私域知识”的问题但如果任务要求模型完成多步操作例如查询天气、调用数据库、发送邮件仅靠对话生成就不够了。这时需要 Agent 能力。Agent 的核心机制是 Function Calling函数调用。模型在生成回答时可以输出结构化指令表示“我需要调用某个函数”而不是直接生成普通文本。应用收到指令后执行对应的函数把执行结果返回给模型模型再根据结果继续生成最终回答。这个机制让大模型从“文本生成器”变成了“任务调度器”。它可以自主决定调用哪个工具、传什么参数、根据工具结果决定下一步动作。5.2 Function Calling 最小示例假设我们有一个获取城市天气的函数希望让模型根据用户问题自动判断是否需要调用该函数。首先定义函数def get_weather(city: str) - str: 模拟获取天气信息实际项目中可以替换为真实天气 API。 weather_map { 北京: 晴25°C, 上海: 多云28°C, 广州: 小雨30°C, } return weather_map.get(city, 暂不支持该城市天气查询)然后调用 Chat Completions 接口并把tools参数传入# 文件路径demo_function_call.py import os import json from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL), ) def get_weather(city: str) - str: weather_map { 北京: 晴25°C, 上海: 多云28°C, 广州: 小雨30°C, } return weather_map.get(city, 暂不支持该城市天气查询) messages [ {role: user, content: 北京今天天气怎么样}, ] tools [ { type: function, function: { name: get_weather, description: 查询指定城市今天的天气情况, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如北京, } }, required: [city], }, }, } ] response client.chat.completions.create( modelos.getenv(OPENAI_MODEL), messagesmessages, toolstools, tool_choiceauto, ) message response.choices[0].message print(模型返回内容, message.content) print(工具调用, message.tool_calls) if message.tool_calls: for tool_call in message.tool_calls: name tool_call.function.name arguments json.loads(tool_call.function.arguments) if name get_weather: result get_weather(cityarguments[city]) messages.append(message) messages.append({ role: tool, tool_call_id: tool_call.id, content: str(result), }) second_response client.chat.completions.create( modelos.getenv(OPENAI_MODEL), messagesmessages, toolstools, ) print(最终回答, second_response.choices[0].message.content)5.3 Agent 工程化的注意事项Function Calling 在示例中看起来很简单但工程化落地时需要注意几个问题。第一工具描述要详细。模型的函数调用判断依赖description字段描述越清晰调用准确率越高。第二参数校验不能省。模型返回的参数格式虽然遵循 JSON Schema但仍可能缺少必填字段或者参数值不在预期范围内执行函数前必须校验。第三要考虑多轮调用的上限。一个复杂 Agent 任务可能需要多次调用工具开发时需要设置最大轮数防止死循环和成本失控。实际项目中Agent 还可以接入记忆模块把历史对话和已执行的操作记录下来帮助模型在长任务中保持状态。但记忆模块会增加系统复杂度建议先从简单的单工具调用开始逐步增加能力。6. 常见问题与排查思路6.1 API 返回错误问题现象常见原因解决思路AuthenticationErrorAPI Key 填错或已过期检查.env文件中的密钥确认没有空格NotFoundError模型名称不存在或账号无权访问该模型确认模型标识是否正确检查服务商的模型列表RateLimitError请求频率超出限制增加重试机制考虑降低并发或联系服务商提高限额APIConnectionError网络无法连接到模型服务检查网络、代理设置确认 base_url 是否正确ContextLengthExceeded输入消息超过模型上下文窗口精简 Prompt或对历史消息做截断和摘要6.2 输出质量不稳定模型输出不稳定是一个高频问题尤其是同一个 Prompt 在不同时间得到不同结果。排查时先看temperature参数如果设置过高模型输出随机性会明显增强。其次是 Prompt 是否足够明确输出格式是否做了硬性约束。还可以尝试在 Prompt 末尾增加“请确认你的回答符合上述要求”这类提示有时能提升输出稳定性。更系统的方法是建立评估集。准备 20 到 50 个测试问题以及对应的期望回答标准每次修改 Prompt 或更换模型时运行一轮评估对比输出质量。不要凭一两次测试的结果判断模型好坏。6.3 本地部署推理缓慢本地模型推理速度慢通常与硬件和推理框架选择有关。显存不足时模型会使用 CPU 或内存做部分计算速度会大幅下降。解决方案包括使用量化模型减少显存占用例如 4bit 量化选择推理效率更高的框架例如 vLLM在推理服务中开启动态批处理提高 GPU 利用率。如果显存和性能仍然不够建议回到 API 调用方案或者使用更小的模型版本。6.4 检索不到相关内容RAG 项目中最常见的现象是知识库里明明有答案但模型就是回答不出来。排查时先检查文本切分粒度。如果文本块太小单块包含的信息有限如果文本块太大超过模型上下文窗口检索精度也会下降。其次是嵌入模型的质量哈希向量和简单的嵌入模型对语义理解有限建议换成更专业的 Embedding 模型。可以打印检索命中的文本块查看命中的内容是否真的包含问题答案。如果检索结果本身就不相关问题出在检索环节如果检索结果相关但回答错误问题出在 Prompt 或大模型环节。6.5 安全与合规风险大模型应用上线前必须做安全审查。尤其是面向外部用户的产品要防止 Prompt 注入、敏感信息泄露、生成违规内容等风险。建议在系统层面对输入输出做内容和关键词审核对模型返回结果进行二次过滤。涉及用户数据和业务数据时严格遵守最小权限原则只把必要的数据传给模型。如果业务涉及生产环境和真实数据所有变更都要先在测试环境验证做好备份和回滚方案避免出现数据丢失或不可恢复的问题。7. 最佳实践与工程建议7.1 模型选型要结合成本与效果大模型选型不能只看跑分要结合业务场景、数据规模、调用频率、预算和响应速度综合判断。对于那些需要处理大量简单文本的场景选择小尺寸模型即可成本低、响应快对于复杂推理、代码生成、长文本理解场景再考虑大尺寸模型。建议在项目初期同时接入多个模型供应商通过统一的封装层隔离差异。这样既可以在不同模型之间做 A/B 测试也可以在某一家服务不稳定时快速切换降低供应商锁定风险。7.2 把 Prompt 当作代码管理Prompt 不是“一次性写好的提示语”而是需要版本管理的应用资产。建议把实际业务中使用的 Prompt 写在单独的配置文件中使用 Prompts 文件管理。修改 Prompt 时遵循代码评审流程记录每次变更的原因。项目目录中可以单独建一个prompts文件夹按业务功能划分文件。同一个 Prompt 模板要避免在多个 Python 文件中重复复制。否则修改一处其他位置的 Prompt 还是旧版本排查起来非常麻烦。7.3 建立模型输出缓存大模型 API 调用有延迟费用也不便宜。对于相同问题、相同参数、相同上下文的重复请求可以使用缓存层直接返回结果减少 API 调用次数。缓存键可以设计为“模型名称 Prompt 用户输入 主要参数”的哈希值缓存的过期时间根据业务需求设置。注意涉及实时数据的场景不要使用长时间缓存。7.4 日志与可观测性大模型应用的可观测性比传统应用更复杂因为同一个 Prompt 可能产生不同输出。建议在日志中记录以下字段请求时间、用户标识、会话标识模型名称、版本、temperature 等参数输入消息摘要和输出消息摘要Token 使用量、响应耗时是否触发工具调用、调用了哪些工具错误信息和重试次数有了这些日志才能在线上问题出现时回溯分析判断是模型问题、参数问题还是业务逻辑问题。7.5 安全边界与数据隐私在 AI 应用中数据隐私是绝对不能忽视的问题。把数据发送给外部模型服务前要明确数据中是否包含敏感信息。对敏感字段做脱敏处理后再调用模型。如果使用外部模型服务有合规风险考虑本地部署方案确保数据不出内网。同时要防止 Prompt 注入攻击。例如知识库内容可能被恶意构造让模型忽略原有指令。开发时应对知识库内容进行来源审查并对模型输出中的异常指令保持警惕。7.6 从 API 到生产的落地顺序建议遵循“Prompt → RAG → Fine-tuning → 本地部署”的演进路径。先通过优化 Prompt 解决大部分问题再引入 RAG 解决私域知识问题仍然不满足需求时考虑微调。本地部署放在最后因为它涉及 GPU 资源、推理框架和运维成本没有充分的理由不要轻易上。每一步都做好测试和评估不要为了追求“更高级”的方案而增加不必要的复杂度。一个大模型应用项目是否成功最终要看业务效果是否提升而不是用了多复杂的模型。8. 总结与下一步学习建议本文从大模型应用开发的背景出发逐步介绍了模型选型、API 调用、流式输出、本地部署思路、Prompt 设计、RAG 问答助手、Function Calling 和 Agent 工程化。通过完整案例演示了如何读取知识库、构建索引、检索文本块、调用大模型生成答案并整理了常见的错误排查方法和工程建议。如果这是你接触大模型开发的第一篇文章建议先把第 3 章的 API 调用示例跑通再动手实践第 4 章的问答助手。过程中遇到报错不要慌先确认环境变量是否正确、模型名称是否有效、网络是否能连通再逐步排查代码逻辑。下一步可以从三个方向继续深入一是学习如何使用真正的 Embedding 模型和向量数据库如 PGVector、Milvus、Redis Search把 RAG 案例升级为生产级实现二是研究 Spring AI 或 LangChain 这类框架的源码和设计思路理解工具调用、Agent 编排的抽象方式三是关注模型评测和成本优化建立一套属于自己团队的模型评估体系。大模型技术迭代很快今天的最佳实践可能很快就会过时。但只要掌握了“概念理解 → 环境验证 → 最小实现 → 工程化打磨”这套方法无论技术怎么变你都能快速上手。动手写代码永远是最好的学习方式。