之前在梳理大模型学习路线时经常被问到一个问题理论看了不少但距离“自己动手做一个 LLM 应用”还有多远后来看到datawhalechina/happy-llm这个开源学习项目才发现很多人在同一条路上踩过类似的坑。市面上讲大模型原理的资料很多但能让人从 Prompt 一直走到 RAG、Agent并且每一步都有可运行案例的教程并不多。这篇文章不会逐章照搬某个仓库的目录而是结合happy-llm这类项目传递的学习方法整理出一份更通用的 LLM 入门与实践笔记。文章会从基础概念讲起再带大家完成一个本地问答应用的完整示例。无论你是刚接触大模型的研发同学还是准备在业务里引入 LLM 的技术负责人都能从中找到可以直接落地的思路。1. 背景与核心概念1.1 LLM 是什么为什么大家都在学LLM 是 Large Language Model 的缩写中文通常叫“大语言模型”。它本质上是基于深度学习训练出来的文本生成模型通过学习海量语料掌握了语言的统计规律和知识表示能力。常见的开源模型如 Llama、Qwen、DeepSeek 系列都属于这个范畴。我们可以用一句话理解传统程序是人写规则、机器执行而 LLM 是机器从数据里“学”出规则再根据输入生成输出。这带来了一个关键转变——很多以前需要人工梳理规则的任务现在可以通过自然语言描述目标让模型去完成。应用场景非常广泛智能问答客服、知识库问答、企业内网问答。内容生成文案、代码、报告、摘要。信息抽取从非结构化文本中提取结构化信息。代码助手代码补全、解释、评审。数据分析用自然语言查询数据库、生成图表。大模型的能力边界还在快速扩展但“知道 LLM 能做什么”和“能稳定地把 LLM 用起来”是两件事。绝大多数入门者卡在了后面这件事上这也是本文想重点解决的问题。1.2 datawhalechina/happy-llm 项目定位datawhalechina/happy-llm是 Datawhale 社区维护的一个开源学习项目。Datawhale 是一个以开源学习为主的技术社区组织过很多人工智能方向的组队学习活动。这个项目命名里的 “happy” 本身就有一点“让大模型学习变得轻松”的意味。从项目内容通常覆盖的范围来看这类教程一般会包括LLM 基础概念什么是 Token、上下文、温度系数。Prompt 工程如何设计高质量提示词。微调入门LoRA、全量微调的基本流程。RAG 检索增强生成如何让模型基于私有知识回答问题。Agent 应用让模型调用工具、完成多步骤任务。需要注意的是开源仓库的结构和内容会随维护进度调整不同分支、不同版本之间的差异也比较大。读者不必纠结于记住某个具体文件路径更重要的是抓住项目的学习主线再根据自己的基础选择章节。1.3 本文适合哪些读者如果你属于下面某一类本文会比较适合刚开始接触 LLM想建立系统知识框架的同学。已经会调用大模型 API但不太清楚 RAG、Agent、精度这些概念具体怎么落地。后端工程师需要在业务系统里集成 LLM 能力。准备做技术选型想了解本地部署、API 调用、微调、RAG 到底怎么配合使用。本文的核心思路是先理解概念再做最小可运行示例最后总结工程化建议。读完后你应该能自己搭建一个本地问答应用并对后续学习方向有清晰的判断。2. 环境准备与版本说明2.1 硬件与运行环境大模型开发对环境的要求比较有弹性分为“调用 API”和“本地部署”两种情况。如果只是调用云端 API比如 OpenAI 兼容接口、国内大模型厂商的接口那么普通开发电脑就够用重点是网络和密钥配置。如果需要本地部署开源模型硬件影响就比较大CPU 推理速度慢适合模型较小或非实时场景。单张消费级 GPU比如 8GB、12GB、24GB 显存适合用 Ollama、llama.cpp 运行量化后的 7B、14B 模型。多张数据中心 GPU适合微调和更大规模部署。对于入门阶段推荐的做法是先用 API 跑通业务逻辑再根据效果决定是否本地化部署。不要一上来就追求本地跑满血大模型成本会很高。操作系统方面Windows、macOS、Linux 都可以。macOS 用户如果使用的是 Apple Silicon可以尝试 MLX 或 Ollama 这类针对苹果芯片优化的推理方案性能表现不错。Windows 用户需要留意 WSL 的使用很多开源工具的 Linux 版本更成熟。2.2 Python 与依赖安装本文示例使用 Python 3.10 以上版本。建议通过虚拟环境隔离项目依赖避免不同项目之间的包版本互相冲突。python -m venv .venv source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate pip install --upgrade pip后面示例会用到以下依赖可以先安装pip install openai fastapi uvicorn pydantic requests numpyopenai库不只是能访问 OpenAI 官方服务它也支持很多兼容 OpenAI 接口协议的本地推理服务。只要暴露的是/v1/chat/completions接口基本都可以使用同一个客户端代码。这也是目前大模型生态中非常流行的兼容方式。2.3 模型获取与本地部署本地部署最简单的方式之一是使用 Ollama。它把模型管理、下载、启动推理服务集成在一起对初学者很友好。安装后拉取模型即可ollama pull qwen2.5:7b ollama serve启动服务后默认会监听http://localhost:11434并且提供了 OpenAI 兼容的访问路径通常是http://localhost:11434/v1。版本选择建议不要盲目追求最新版本应该根据显存大小和业务场景选择合适参数的模型。7B 模型在量化后大约需要 4GB 到 6GB 显存13B 模型则需要更多。如果你的设备跑不动优先选择更小的模型而不是强行加载大模型。3. LLM 核心知识拆解3.1 精度问题FP16、FP32、BF16 怎么选在大模型领域“精度”是指模型权重和计算过程中数值的表示方式。不同精度占用内存不同计算速度也不同还会影响模型输出的稳定性。常见的有三种精度类型位宽特点典型场景FP3232 位表示范围大数值稳定占内存多训练早期、小模型、精度敏感场景FP1616 位半精度计算快但表示范围小推理加速、显存有限时使用BF1616 位指数位和 FP32 相同表示范围大尾数精度稍低大模型预训练、混合精度训练FP16 的问题是数值范围容易溢出。BF16 用更多的指数位换来了和 FP32 几乎一致的表示范围所以在大模型训练中更受欢迎。推理时如果模型本身是 FP16 训练出来的在支持 BF16 的显卡上可以尝试用 BF16 做推理。量化则是对权重的进一步压缩比如 8 位、4 位量化。量化后模型体积变小、推理速度变快但可能带来一定的精度损失。对于很多问答场景4 位量化模型依然有可用的效果这也是 Ollama 等工具能在消费级显卡上运行大模型的关键原因。实践建议显存紧张优先选择量化模型。追求效果使用更高精度或直接调用云端 API。微调场景明确训练框架支持哪些精度不要随意混用。3.2 Prompt、提示工程与上下文窗口Prompt 是用户输入给模型的指令和上下文。大模型本身不会“读心”它只能根据提供的文本生成后续内容。因此Prompt 的质量直接影响输出质量。一个有效的 Prompt 通常包含几个要素角色设定告诉模型你希望它扮演什么角色比如“你是一名资深算法工程师”。任务描述明确要让模型完成什么。输入内容提供需要处理的数据。输出约束指定格式、长度、语气。例如你是一名数据库专家。请根据下面的表结构生成一条 SQL 查询语句要求查询近7天订单金额大于1000元的用户数量。 表结构 orders(id, user_id, amount, created_at) 请只输出 SQL不要输出多余解释。上下文窗口Context Window表示模型能一次性“看到”的 Token 数量。Token 可以粗略理解为文本的切分单位中文字符可能对应一个或多个 Token。上下文窗口越大能容纳的输入输出内容越多但计算成本也会上升。常见误区是认为 Prompt 越长越好。实际上无关信息会干扰模型判断还容易浪费上下文容量。在工程实践中应该对 Prompt 做精简只保留完成任务所必需的信息。3.3 RAG让大模型学会“查资料”大模型的知识来自训练数据因此存在两个问题知识更新滞后且不具备企业内部私有知识。RAG全称 Retrieval-Augmented Generation也就是检索增强生成通过“先检索、再生成”的方式解决这个问题。流程可以拆成四步把私有文档切分成片段做向量化处理存入向量数据库。用户提问时将问题也向量化。在向量数据库中检索最相似的文档片段。把检索到的片段和用户问题一起组装成 Prompt交给大模型生成回答。这样做的好处是模型不需要记住所有知识只需要在回答时“查资料”既能做知识更新也能在一定程度上缓解模型“一本正经地胡说八道”的问题。RAG 的关键点在于文档切分策略要合理。向量化模型和查询问题要匹配。检索结果需要按相关性排序并控制数量。最终答案要标注来源方便人工核验。3.4 Agent 与 MCP从问答到任务执行如果说 RAG 让模型会“查”那么 Agent 让模型会“做”。Agent 可以理解为一个智能体它能够拆解任务、调用工具、观察结果、调整计划直到完成任务。常见的 Agent 能力包括调用搜索引擎。执行代码。调用业务 API。操作数据库。读取本地文件。这里会涉及工具调用的概念。模型并不直接执行操作而是根据用户需求生成“需要调用某个工具”的结构化指令程序再去执行并把结果返回给模型继续处理。MCPModel Context Protocol是近期比较受关注的协议方向。它试图统一大模型与外部工具、数据源之间的连接方式。简单理解MCP 相当于为大模型提供了一套标准化的“插座”不同的工具只要实现对应协议模型就能调用降低了工具接入的耦合成本。对于初学者不用急着追所有概念。先理解 Agent 的本质是“模型 工具 循环”再在具体框架里实践即可。另外有一个很常见的问题ComfyUI 和 LLM 必须在同一台电脑上吗答案是否定的。ComfyUI 是图像生成工作流工具LLM 是语言模型服务两者可以通过 HTTP API 分别部署在不同机器上只要网络能够互通即可。同样微调、推理、向量数据库也可以拆分部署。4. 完整实战案例搭建一个本地问答应用下面通过一个最小可运行的案例把前面介绍的概念串起来。这个案例会实现一个基于 FastAPI 的问答服务核心逻辑包括调用 LLM 接口生成回答。使用向量检索完成私域知识问答。暴露 HTTP 接口方便前端或其他服务调用。4.1 项目结构设计llm-demo/ ├── main.py # FastAPI 入口 ├── rag.py # RAG 检索逻辑 ├── llm_client.py # LLM 调用封装 ├── requirements.txt └── README.md先解释一下设计思路llm_client.py单独管理模型调用后续如果替换模型服务只改这一个文件rag.py负责文档加载、切分、向量化和检索main.py只负责 HTTP 层逻辑。4.2 创建依赖文件# requirements.txt openai fastapi uvicorn pydantic requests numpy4.3 封装 LLM 调用# 文件路径llm-demo/llm_client.py from openai import OpenAI class LLMClient: def __init__(self, base_url: str http://localhost:11434/v1, api_key: str EMPTY): self.client OpenAI(base_urlbase_url, api_keyapi_key) def chat(self, messages: list, temperature: float 0.7) - str: response self.client.chat.completions.create( modelqwen2.5:7b, messagesmessages, temperaturetemperature, ) return response.choices[0].message.content这里的base_url指向 Ollama 的 OpenAI 兼容接口。如果你的环境调用的是云端 API改成对应服务商提供的地址和密钥即可。4.4 实现 RAG 检索逻辑# 文件路径llm-demo/rag.py import numpy as np from openai import OpenAI class SimpleRAG: def __init__(self, base_url: str http://localhost:11434/v1, api_key: str EMPTY, embedding_model: str text-embedding-model): self.client OpenAI(base_urlbase_url, api_keyapi_key) self.embedding_model embedding_model self.documents [] def add_documents(self, docs: list): self.documents.extend(docs) def _embed(self, text: str): resp self.client.embeddings.create(modelself.embedding_model, input[text]) return resp.data[0].embedding def similarity(self, a, b): a np.array(a) b np.array(b) return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))) def search(self, query: str, top_k: int 1) - list: q_vec self._embed(query) scored [] for doc in self.documents: doc_vec self._embed(doc) score self.similarity(q_vec, doc_vec) scored.append((doc, score)) scored.sort(keylambda x: x[1], reverseTrue) return scored[:top_k]上面是一个演示用的极简实现每次检索都会重新计算文档向量。真实项目中应该使用向量数据库缓存文档向量避免重复计算。如果你在本地环境中配置了文本向量 API模型名称和地址会有所不同需要在代码中调整。4.5 组合问答服务# 文件路径llm-demo/main.py from fastapi import FastAPI from pydantic import BaseModel from llm_client import LLMClient from rag import SimpleRAG app FastAPI() llm LLMClient() rag SimpleRAG() rag.add_documents([ RAG 是检索增强生成技术通过外部知识库提升大模型回答准确性。, MCP 是模型上下文协议用于统一大模型与外部工具的数据连接。, FP16 和 BF16 都是半精度格式BF16 的数值范围更接近 FP32。, ]) class AskRequest(BaseModel): question: str app.post(/ask) def ask(request: AskRequest): question request.question results rag.search(question, top_k1) context results[0][0] if results else messages [ {role: system, content: 你是一个中文知识助手请基于提供的资料回答问题。}, {role: user, content: f资料{context}\n\n问题{question}\n\n请简要回答。}, ] answer llm.chat(messages) return {answer: answer, evidence: context}这个示例的关键点在于先通过检索拿到与问题最相关的资料再把资料拼进 Prompt最后让模型生成回答。这样一来回答不再是模型“凭空想出来”的而是有资料依据的。4.6 启动服务与验证uvicorn main:app --host 0.0.0.0 --port 8000服务启动后可以用curl验证接口curl -X POST http://localhost:8000/ask \ -H Content-Type: application/json \ -d {question: 什么是 RAG}预期会返回类似下面的结果{ answer: RAG 是检索增强生成技术通过先检索相关资料再生成回答的方式让模型能够利用外部知识库提升准确性。, evidence: RAG 是检索增强生成技术通过外部知识库提升大模型回答准确性。 }如果你的环境中没有可用的 embedding 模型可以把SimpleRAG替换为一个固定的相似度计算实现或者直接在messages中只传资料与问题效果会弱一些但能先把主流程跑通。5. 常见问题与排查思路在实际操作中最容易遇到下面这些问题。问题现象常见原因解决思路请求超时本地模型加载慢或服务未启动检查模型服务状态延长超时时间返回内容为空Prompt 格式错误或模型被安全策略拦截检查 messages 格式尝试简化输入显存不足模型过大或并发过高换小模型、启用量化、限制并发回答内容与资料无关检索结果不相关改进切分策略增加 top_k优化检索模型向量 API 未配置代码中 embedding 模型不存在配置正确的模型名、地址和密钥细节与官网不一致版本更新导致行为变化以官方文档为准固定版本排查这一类问题时推荐按顺序做三层检查先确认模型服务本身可用直接通过 curl 调用 chat 接口排除业务代码问题。再确认输入输出格式检查 messages 中每条消息的 role 和 content。最后确认检索链路看返回的证据片段是否真的包含答案。最有效的调试方法是把每次请求的 Prompt 完整打印出来。很多“模型回答不对”的问题本质上是 Prompt 里给的信息不够清晰。6. 最佳实践与工程建议6.1 配置管理与密钥安全LLM 项目的配置项非常多比如接口地址、模型名称、温度系数、上下文长度、向量库地址等。建议通过配置中心或环境变量管理不要硬编码在代码里。所有 API 密钥必须放在服务端环境变量中禁止提交到 Git 仓库。可以通过.gitignore排除.env文件。密钥泄露的风险不只是扣费还可能被恶意调用导致不可控的资源和合规风险。6.2 成本、速度与效果的平衡调用云端大模型 API 是按 Token 计费的同一段文本在不同模型下的 Token 计算方式也可能不同。工程上的常见优化手段包括对用户输入做长度限制。对 Prompt 做压缩去掉冗余内容。对高频问题使用缓存。根据任务复杂度选择不同规格的模型。另外要避免把大模型当成“万能处理中心”。适合用正则、规则和传统 NLP 解决的问题就用轻量方案解决只有涉及语义理解、生成和决策时才调用大模型。6.3 可观测性与日志大模型应用的日志比普通应用更关键。因为模型输出不确定出了问题需要能回放当时的 Prompt、参数和模型版本。建议至少记录请求 ID 和用户 ID。输入内容和输出内容。模型名称、温度、上下文窗口等参数。响应耗时和 Token 消耗。检索到的证据片段。如果业务对准确性要求高建议建立人工评测集每次升级 Prompt 或模型后先在测试集上对比效果避免直接全量上线。6.4 安全边界与权限在业务系统中使用 LLM 时要注意接口层面的鉴权。如果你的服务通过 FastAPI 暴露给外部使用至少应该增加 Token 鉴权避免被任意调用。更进一步的建议限制单用户调用频率。对用户输入做敏感信息过滤。对模型输出做合规审查。不要让模型直接操作生产数据库或执行高权限命令。涉及用户隐私数据时确保模型服务部署在符合安全要求的环境中。关于“LLM API 授权过度”这一类安全风险核心是防止模型被诱导去调用超出权限范围的工具或接口。Agent 越强大越要限定它的能力边界。7. 总结与学习路线7.1 掌握要点回顾通过这篇文章我们系统的走了一遍 LLM 从概念到实践的路径。你可以回忆起这样几条主线。第一LLM 的核心在于用自然语言描述任务让模型基于学习到的知识生成内容但它的知识有截止时间也缺少私有数据所以需要 RAG 来补充资料需要 Agent 来执行动作。第二工程的复杂度不在于单次调用而在于把模型、检索、工具调用、权限控制组合成一个稳定的服务。一个最小可运行的问答服务应该具备清晰的模块边界。第三精度、显存、模型规模这些参数不是选最大的就好而是要结合硬件条件、效果预期和成本做取舍。7.2 下一步可以怎么学如果你已经能跑通上面的小项目下一步建议按这个顺序深入精读一个 Prompt 工程教程学会写结构化、可验证的 Prompt。尝试用向量数据库比如 Chroma、Milvus、Elasticsearch替代上面示例里的简单列表。学习一个 Agent 框架理解工具注册、任务规划、结果回传是怎么实现的。学习微调的基本概念尤其是 LoRA 这类参数高效微调方法。关注 MCP 等协议的发展了解如何统一接入外部工具减少重复开发。开源社区里有很多学习材料可以参考datawhalechina/happy-llm可以作为入门导览Andrej Karpathy 整理的 “llm wiki” 提供了大量高质量资料索引Datawhale 的其他实战项目也值得持续跟踪。技术发展很快但“理解概念、动手实践、沉淀工程经验”这条学习路径不会变。建议先跑通一个小项目再根据实际需要选择方向深挖比一直停留在“看教程”阶段有效得多。