LlamaAI 本地部署实战专栏·第10篇终章前9篇我们从 llama.cpp、GGUF、CUDA、API、RAG、Hybrid Search、Agent 一路学习下来。这一篇不再拆开讲单个技术而是把所有模块真正组合起来完成一个可以运行、可以演示、也可以继续扩展的本地AI智能助手。项目最终目标不依赖云端LLM API在自己的电脑上完成模型推理、知识库检索、工具调用和Web聊天。一、先看看最终项目长什么样我们最终要做的是┌──────────────┐ │ 用户 │ └──────┬───────┘ │ ↓ ┌──────────────┐ │ Web UI │ │ Vue / HTML │ └──────┬───────┘ │ HTTP ↓ ┌──────────────┐ │ FastAPI │ └──────┬───────┘ │ ↓ ┌──────────────┐ │ AI Agent │ └──────┬───────┘ │ ┌─────────────┼─────────────┐ ↓ ↓ ↓ RAG Tool File Tool LLM │ │ │ ↓ ↓ ↓ BM25 FAISS 本地文件 llama.cpp │ │ ↓ ↓ Reranker CUDA GPU │ │ └─────────────┬─────────────┘ ↓ GGUF ↓ AI最终答案这就是本专栏最终的LlamaAI本地智能助手。二、项目最终具备什么能力完成之后你可以直接在浏览器中http://localhost:8000打开聊天页面。然后输入CUDA和TensorRT有什么区别Agent可以直接回答。输入根据我的PDF总结一下TensorRT优化方法。系统会用户 ↓ Agent ↓ RAG ↓ 搜索PDF ↓ Reranker ↓ Llama ↓ 答案甚至可以帮我读取项目README然后总结项目结构。AgentLLM ↓ 调用文件工具 ↓ 读取README ↓ 分析 ↓ 返回结果这已经不是简单的Chatbot。而是本地AI Agent。三、项目技术栈我们先确定技术栈。模块技术LLMQwen / Llama GGUF推理引擎llama.cppGPUCUDA模型格式GGUFAPI Serverllama-server后端Python FastAPIEmbeddingBGE向量检索FAISS关键词检索BM25重排序RerankerAgentPython前端Vue 3数据本地文件最终Python llama.cpp CUDA FAISS Vue组成完整系统。四、项目目录设计不要把所有代码塞进一个main.py里面。一个比较合理的工程结构LlamaAI/ │ ├── backend/ │ │ │ ├── main.py │ │ │ ├── config.py │ │ │ ├── api/ │ │ └── chat.py │ │ │ ├── agent/ │ │ ├── agent.py │ │ ├── runtime.py │ │ └── tools/ │ │ ├── calculator.py │ │ ├── file.py │ │ └── rag.py │ │ │ ├── rag/ │ │ ├── ingest.py │ │ ├── embedding.py │ │ ├── bm25.py │ │ ├── vectorstore.py │ │ └── reranker.py │ │ │ └── llm/ │ └── client.py │ ├── frontend/ │ ├── src/ │ │ ├── App.vue │ │ └── components/ │ │ │ └── package.json │ ├── models/ │ ├── llm/ │ │ └── model.gguf │ │ │ └── embedding/ │ ├── data/ │ └── documents/ │ ├── vectorstore/ │ └── README.md这个结构有一个非常重要的特点模型、RAG、Agent、API、前端彼此解耦。五、第一步准备本地LLM上一篇已经完成llama.cpp CUDA GGUF现在假设models/ └── llm/ └── qwen.gguf启动llama-server \ -m models/llm/qwen.gguf \ -ngl 999 \ -c 4096 \ --flash-attn \ --port 8080启动成功Server listening on port 8080此时localhost:8080已经成为我们的本地LLM服务。六、第二步Python连接本地Llama安装pip install openai创建backend/llm/client.py代码from openai import OpenAI client OpenAI( base_urlhttp://localhost:8080/v1, api_keylocal )测试response client.chat.completions.create( modellocal-model, messages[ { role: user, content: 什么是CUDA } ] ) print( response.choices[0].message.content )如果能够返回答案CUDA是NVIDIA推出的并行计算平台...说明Python ↓ llama-server ↓ 本地模型已经打通。七、第三步建立RAG知识库准备data/documents/放入CUDA.pdf TensorRT.pdf llama.cpp.pdf 项目说明.md执行ingest.py流程PDF ↓ Text Extraction ↓ Chunk ↓ Embedding ↓ FAISS ↓ BM25最终生成vectorstore/ ├── faiss.index ├── chunks.json └── bm25.pkl八、为什么要保存chunksFAISS里面主要保存的是Vector但是我们真正需要给LLM的是原始文本因此FAISS Vector ↓ ID然后ID ↓ chunks.json ↓ 原始文本例如{ 0: CUDA是一种GPU并行计算平台..., 1: TensorRT是NVIDIA推出的推理优化SDK... }这样检索到ID 17就能找到chunk 17九、第四步实现Hybrid Retriever我们的检索器backend/rag/负责Query ↓ BM25 ↓ FAISS ↓ RRF ↓ Top-K核心逻辑def retrieve(query): bm25_results search_bm25(query) vector_results search_faiss(query) results rrf( bm25_results, vector_results ) return results[:10]这样Agent就不需要知道FAISS到底怎么工作的。Agent只需要调用retrieve(query)即可。这就是模块封装。十、第五步加入RerankerRRF之后Top 20然后Reranker ↓ Top 5例如def rerank(query, documents): scores reranker.predict( [ [query, doc] for doc in documents ] ) return sort_by_score( documents, scores )最终Query ↓ Hybrid Search ↓ Top 20 ↓ Reranker ↓ Top 5这样给LLM的上下文更加干净。十一、第六步把RAG封装成Tool创建backend/agent/tools/rag.py例如def search_knowledge(query): documents retrieve(query) documents rerank( query, documents ) return documents现在对于Agent来说search_knowledge()就是一个普通工具。Agent不需要知道BM25 FAISS RRF Reranker这些复杂实现全部隐藏在Tool内部。十二、第七步增加文件工具例如def read_file(path): with open( path, r, encodingutf-8 ) as f: return f.read()以及def list_files(path): import os return os.listdir(path)现在Agent拥有Tools │ ├── search_knowledge ├── read_file └── list_files以后还可以继续增加calculator weather database browser python十三、第八步Agent RuntimeAgent真正的核心agent/runtime.py工作流程User ↓ LLM ↓ Tool Call? ├── No → Final Answer │ └── Yes ↓ Execute Tool ↓ Tool Result ↓ LLM ↓ Tool Call?代码思想while True: response call_llm( messages, tools ) if not response.tool_calls: return response.content for tool_call in response.tool_calls: result execute_tool( tool_call ) messages.append( result )这就是Agent Loop。十四、Agent到底“智能”在哪里并不是Agent 更大的模型而是LLM ↓ 观察当前信息 ↓ 决定下一步 ↓ 执行Tool ↓ 观察结果 ↓ 决定下一步例如用户找出项目中关于CUDA的资料并总结GPU优化方法。Agent可能第1步 search_knowledge(CUDA GPU优化)得到CUDA文档 llama.cpp文档 TensorRT文档然后第2步 继续分析最终第3步 生成总结这就是多步骤任务执行。十五、第九步FastAPI作为统一后端安装pip install fastapi uvicorn创建backend/main.py代码from fastapi import FastAPI app FastAPI() app.get(/) def root(): return { message: LlamaAI }启动uvicorn backend.main:app \ --host 0.0.0.0 \ --port 8000访问http://localhost:8000后端服务FastAPI启动完成。十六、第十步实现聊天接口例如app.post(/chat) def chat(request): answer agent.run( request.message ) return { answer: answer }现在整个系统Browser ↓ POST /chat ↓ FastAPI ↓ Agent ↓ Llama十七、第十一步加入流式输出如果每次等待模型全部生成 ↓ 一次性返回体验会很差。因此使用Streaming效果你 ↓ 你好 ↓ 你好我 ↓ 你好我是 ↓ 你好我是一个 ↓ ...用户会感觉AI正在实时回答。这也是聊天类应用非常重要的UX设计。十八、第十二步Vue前端如果你熟悉Vue 3可以直接创建npm create vitelatest frontend选择Vue TypeScript安装cd frontend npm install npm run dev最终Vue ↓ FastAPI ↓ Agent十九、聊天页面最核心的结构页面可以非常简单┌─────────────────────────────────┐ │ LlamaAI │ ├─────────────────────────────────┤ │ │ │ User: CUDA是什么 │ │ │ │ AI: CUDA是NVIDIA的GPU计算平台… │ │ │ │ User: 根据我的PDF解释一下… │ │ │ │ AI: 根据知识库检索结果… │ │ │ ├─────────────────────────────────┤ │ 输入问题................ [发送] │ └─────────────────────────────────┘第一版不要追求复杂UI。先确保前后端链路稳定。二十、整个请求到底经过了多少层用户输入TensorRT如何优化LLM推理实际上经历用户 ↓ Vue ↓ HTTP POST ↓ FastAPI ↓ Agent ↓ LLM ↓ 判断需要知识检索 ↓ RAG Tool ↓ ┌───────┴───────┐ ↓ ↓ BM25 FAISS ↓ ↓ └───────┬───────┘ ↓ RRF ↓ Reranker ↓ Top 5 ↓ Tool Result ↓ LLM ↓ 最终答案 ↓ FastAPI ↓ Vue ↓ 用户这就是一个完整的Local AI Pipeline。二十一、为什么这个架构适合本地部署因为核心数据全部可以留在本机模型 ↓ 本地 Embedding ↓ 本地 Vector DB ↓ 本地 RAG ↓ 本地 Agent ↓ 本地 Web UI ↓ 本地不需要OpenAI API 云端向量数据库 云端Embedding因此特别适合私人知识库企业内部资料本地开发助手离线环境敏感数据场景AI学习实验二十二、项目启动顺序实际运行时第一步启动llama-serverllama-server \ -m models/llm/qwen.gguf \ -ngl 999 \ -c 4096 \ --port 8080第二步启动FastAPIuvicorn backend.main:app \ --host 0.0.0.0 \ --port 8000第三步启动Vuecd frontend npm run dev第四步浏览器http://localhost:5173二十三、最终端口关系整个系统可以这样理解Vue localhost:5173 │ ↓ FastAPI localhost:8000 │ ↓ llama-server localhost:8080 │ ↓ GGUF CUDA也就是说5173 ↓ 8000 ↓ 8080 ↓ GPU二十四、如何进一步做成真正的产品目前LlamaAI只是一个技术Demo。如果要继续产品化可以增加用户系统Login ↓ User ↓ Conversation多知识库知识库A 知识库B 知识库C会话记忆Conversation ↓ History ↓ MemoryAgent工具市场文件 搜索 数据库 Python Git模型管理Qwen Llama Mistral Gemma最终一个真正的本地AI工作台。二十五、项目的最终架构把整个专栏浓缩成一张图┌───────────────┐ │ User │ └───────┬───────┘ ↓ ┌───────────────┐ │ Vue 3 │ │ Web UI │ └───────┬───────┘ ↓ ┌───────────────┐ │ FastAPI │ └───────┬───────┘ ↓ ┌───────────────┐ │ AI Agent │ └───────┬───────┘ ↓ ┌────────────────┼────────────────┐ ↓ ↓ ↓ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ RAG Tool │ │ File Tool │ │ Other Tool │ └──────┬───────┘ └──────────────┘ └──────────────┘ ↓ ┌──────────────┐ │ Hybrid Search│ └──────┬───────┘ ↓ ┌───────┴────────┐ ↓ ↓ BM25 FAISS │ │ └───────┬────────┘ ↓ RRF ↓ Reranker ↓ Top-K │ └──────────────┐ ↓ ┌───────────────┐ │ llama-server │ └───────┬───────┘ ↓ ┌─────────────┐ │ llama.cpp │ └──────┬──────┘ ↓ CUDA ↓ NVIDIA GPU ↓ GGUF二十六、从工程角度看这个项目学到了什么这个项目真正有价值的地方并不是“我运行了一个Qwen模型。”而是把几个完全不同的技术体系串起来模型推理 ↓ C ↓ CUDA ↓ GPU ↓ HTTP API ↓ Python ↓ RAG ↓ 信息检索 ↓ Agent ↓ Web前端这也是一个比较完整的端侧AI应用工程。二十七、项目还能怎么继续升级如果你准备把这个项目作为GitHub项目CSDN项目简历项目AI比赛作品毕业设计建议继续增加以下功能。1. 多模型切换Model Manager Qwen Llama Gemma Mistral2. 多知识库知识库管理 上传PDF ↓ 自动Embedding ↓ 建立Index3. Conversation Memory让Agent知道你上一轮问了什么形成Short-term Memory Long-term Memory4. Agent可视化例如页面显示Thinking... ↓ Searching Knowledge... ↓ Found 5 documents ↓ Reading README.md ↓ Generating answer...这样用户可以看到Agent正在执行什么任务。注意实际产品中应谨慎设计“思考过程”的展示不要把内部推理链直接暴露展示工具调用状态和执行结果摘要即可。二十八、性能优化路线如果你的GPU比较弱Q4 ↓ -ngl 999 ↓ Context 4096 ↓ Flash Attention ↓ Batch调优如果显存不足降低Context ↓ 降低Batch ↓ 减少GPU Layers ↓ 更低量化如果追求吞吐Batch Parallel GPU如果追求低延迟GPU Offload 合理Context 合理KV Cache二十九、整个专栏的知识地图现在回顾10篇文章LlamaAI │ ↓ ┌──────────────────┐ │ ① 本地LLM基础 │ └────────┬─────────┘ ↓ ┌──────────────────┐ │ ② llama.cpp │ └────────┬─────────┘ ↓ ┌──────────────────┐ │ ③ GGUF模型 │ └────────┬─────────┘ ↓ ┌──────────────────┐ │ ④ CUDA加速 │ └────────┬─────────┘ ↓ ┌──────────────────┐ │ ⑤ llama-server │ └────────┬─────────┘ ↓ ┌──────────────────┐ │ ⑥ RAG │ └────────┬─────────┘ ↓ ┌──────────────────┐ │ ⑦ Hybrid RAG │ │ BM25FAISS │ └────────┬─────────┘ ↓ ┌──────────────────┐ │ ⑧ Agent │ │ Tool Calling │ └────────┬─────────┘ ↓ ┌──────────────────┐ │ ⑨ 性能优化 │ │ KV Cache/CUDA │ └────────┬─────────┘ ↓ ┌──────────────────┐ │ ⑩ 完整LlamaAI │ │ RAGAgentWebUI │ └──────────────────┘三十、专栏最终结语如果你从第一篇一路看到这里那么你已经完成了一次完整的技术升级最开始“怎么在电脑上运行一个本地大模型”后来“怎么让它使用GPU”再后来“怎么把它变成API”然后“怎么让它读取我的知识”再进一步“怎么让它调用工具”最后“怎么把所有东西组合成一个真正的AI应用”最终答案就是LlamaAI │ ┌─────────┴─────────┐ ↓ ↓ LLM Agent │ │ llama.cpp Tools │ │ CUDA RAG │ │ GGUF BM25FAISS │ │ GPU Reranker └─────────┬─────────┘ ↓ FastAPI ↓ Vue ↓ 用户这就是本专栏真正想带你完成的事情不是简单“部署一个模型”而是从模型推理一直走到一个完整的本地AI系统。 LlamaAI本地部署教程——10篇完整目录篇章标题核心技术01从零认识本地大模型LLM、GGUF、llama.cpp02llama.cpp编译与环境搭建CMake、C03GGUF模型下载与本地推理Quantization04llama.cpp CUDA GPU加速CUDA、GPU Offload05llama-server与OpenAI APIHTTP、API06本地Llama RAG知识库Embedding、FAISS07BM25 FAISS工业级RAGHybrid Search、Reranker08本地Llama AgentTool Calling、Agent09llama.cpp性能优化KV Cache、Batch、TPS10完整LlamaAI项目实战LLM RAG Agent WebUI 专栏到这里结束但项目才刚开始如果把这10篇文章真正做成代码你手里得到的就不再是10篇教程而是一个完整的LlamaAI Local AI StackLocal LLM CUDA llama.cpp RAG Hybrid Search Agent FastAPI Vue ↓ 完整本地AI助手这套架构后面还可以继续往三个方向扩展方向一性能工程CUDA Kernel → TensorRT → FlashAttention → Quantization → GPU Profiling方向二AI应用工程RAG → Agent → Memory → MCP → Multi-Agent方向三端侧部署PC GPU → WSL2 → Linux → Android → RK3588 → 边缘设备