面向 localaihub.com 的社区实践帖：目标不是炫技，而是搭出第一套能长期演进的本地 AI 生产栈。它可以先小，但边界要清楚；可以先单机，但接口要能升级；可以先内部使用，但安全和可观测不能缺席。

1. 先定义“本地 AI 第一套生产栈”

很多人说要搭本地 AI，第一反应是下载一个模型，启动一个聊天界面，能回答问题就算完成。这个阶段适合体验，不适合叫生产栈。生产栈至少意味着三件事：有稳定服务边界，有真实数据链路，有可追溯运行证据。

本地 AI 第一套生产栈，不一定要一开始就做 Kubernetes、不一定要多机推理、不一定要训练自己的模型，也不一定要完全离线。更合理的定义是：关键数据和关键推理尽量在自己控制的设备或内网中完成；应用通过统一接口访问模型、向量库和工具；权限、日志、监控、升级和回滚都有基本方案。

这套栈要解决的不是“我能不能和本地模型聊天”，而是“团队能不能把本地模型接进业务流程”。例如：上传内部文档后能问答；查询知识时能带来源；调用工具时不会越权；模型失误时能查到输入、检索片段和工具结果；换模型时应用不需要大改；敏感文档不会随手发到外部 API。

一个务实的第一版可以由六块组成：模型与模型网关、推理服务、嵌入与向量库、检索增强生成、工具调用服务、权限与审计。再加上前端或业务入口、观测和评测，就能形成可迭代底座。

2. 本地优先，不是本地迷信

本地优先的意思是：优先把敏感数据、核心知识库、常用推理和可控工具放在自己边界内。但它不是拒绝云模型，也不是所有任务都必须用本地小模型硬扛。

生产系统可以采用分层策略。低敏任务、日常问答、内部知识检索、批量摘要、离线处理走本地模型。高难推理、复杂代码、长文深度写作、关键多模态分析，可以经过脱敏后调用云模型。嵌入和向量库尽量本地化，因为它们会长期保存知识资产。写操作工具一定要本地受控，因为真正改变业务系统状态的是工具，不是模型文字。

本地优先的价值主要有五个。第一，数据可控，内部文档、日志、客户资料不必默认离开组织边界。第二，低边际成本，高频任务不用每次按 Token 付费。第三，低延迟，局域网推理和检索可以做到很快。第四，可定制，可以按业务知识、语言、权限和审计方式设计系统。第五，抗供应商锁定，模型和推理后端可以替换。

但本地优先也有成本。你要管理模型文件、显存、并发、版本、量化质量、日志、安全补丁和服务稳定性。不要把“本地”理解成天然安全、天然便宜、天然可靠。它只是把控制权拿回来，同时把责任也拿回来。

3. 第一套架构：从单机能跑到团队能用

建议第一套架构不要太散。可以按下面的服务边界搭。

入口层：一个 Web 应用、企业 IM 机器人、命令行工具或内部 API。它负责用户登录、任务提交、结果展示、引用展示和确认操作。

编排层：AI 后端服务。它负责会话、上下文构造、模型路由、RAG 流程、工具调用、状态管理、错误处理和审计日志。应用不要直接从前端访问模型服务，也不要让模型直接访问业务数据库。

模型网关层：对上提供 OpenAI 兼容或自定义统一接口，对下接 Ollama、llama.cpp、vLLM、LM Studio、LocalAI 或云模型。它负责模型选择、超时、重试、限流、流式返回和调用统计。

知识层：文档解析、切块、嵌入、向量库、全文索引、重排和引用管理。它负责把内部资料变成可检索、可权限过滤、可追溯的知识片段。

工具层：封装真实业务能力，例如查订单、查库存、创建工单、发邮件、执行脚本、读取文件。工具层自己做认证、授权、参数校验和审计，不把危险能力裸露给模型。

观测层：记录请求、模型版本、Token、检索片段、工具调用、耗时、错误、用户反馈。没有观测，就没有生产调试。

这个架构即使用一台 Mac mini、一个工作站或一台内网服务器也能起步。关键不是硬件规模，而是边界清楚。

4. 模型选择：别只看参数量

第一套本地 AI 栈通常至少需要三类模型：生成模型、嵌入模型、可选重排模型。

生成模型负责对话、总结、写作、规划和工具参数生成。选择时看中文能力、上下文长度、工具调用稳定性、结构化输出能力、许可证、显存占用和推理速度。7B 到 14B 模型适合轻量任务和低成本常驻；30B 级别模型在复杂理解和写作上更稳；70B 级别质量更好，但硬件门槛明显更高。量化模型可以降低资源占用，但要实测业务任务，不能只看榜单。

嵌入模型负责把文档和问题转成向量。它不需要会聊天，但要在你的语言和领域上检索准确。中文知识库不要随便用只在英文上表现好的嵌入模型。嵌入维度、最大输入长度、吞吐、许可证、是否支持多语言都要看。生成模型和嵌入模型可以来自不同系列，没有必要强行统一。

重排模型负责在初步召回后重新排序候选片段。第一版可以先不用，但一旦知识库规模变大、问题复杂、召回噪音多，重排会明显提升 RAG 质量。重排模型通常比大生成模型便宜，适合作为检索链路中的质量门。

模型选择不要迷信“最新”。应该建立自己的小评测集：二十个内部问答、十个长文摘要、十个工具调用、十个格式输出、十个拒答和权限样本。每次换模型都跑一遍，记录准确率、引用命中、格式合规、延迟和资源占用。

5. 推理后端：Ollama、llama.cpp、vLLM、LM Studio、LocalAI 怎么取舍

如果目标是最快跑起来，Ollama 很合适。它的模型拉取、运行和 API 调用简单，适合开发机、个人工作站和小团队试点。它支持聊天、嵌入、流式输出、结构化输出和工具调用等能力，足够做第一版内部应用。

如果你想深入控制模型文件、量化和底层推理，llama.cpp 是绕不开的项目。GGUF、CPU 推理、Metal、CUDA、多平台构建、server 模式、上下文参数、批处理参数，都能帮助你理解本地模型到底怎样消耗资源。很多桌面和边缘部署都站在 llama.cpp 生态上。

如果你要做多人并发服务，vLLM 更值得关注。它面向高吞吐服务端推理，提供 OpenAI 兼容接口，支持连续批处理、PagedAttention 等优化。它更适合有 GPU 服务器、有并发需求、有统一服务入口的团队。

LM Studio 对桌面用户友好，适合模型试用、人工对比和本地 OpenAI 兼容服务。它可以作为早期验证工具，但团队生产服务最好还是有可脚本化、可监控、可部署的后端。

LocalAI 的价值在于把多种本地推理能力包装成 OpenAI 兼容接口。对已有 OpenAI SDK 或上层应用来说，兼容接口能降低迁移成本。

实践建议是：个人开发用 Ollama 或 LM Studio 快速验证；需要精细优化时用 llama.cpp；需要生产并发时评估 vLLM；需要多后端统一时引入模型网关或 LocalAI。不要把应用代码绑死在某一个后端的特殊参数上。

6. 硬件与容量：从一台机器开始算账

本地 AI 的第一笔账是内存和显存。模型权重占用、KV Cache、并发请求、上下文长度、批处理大小都会消耗资源。一个 7B 4-bit 量化模型可能在普通消费级机器上运行；更大模型、更长上下文、更高并发就需要更强 GPU 或多机方案。

容量规划不要只问“这个模型能不能加载”。还要问：目标上下文长度是多少？同时有几个人使用？平均输出多长？是否需要流式返回？高峰时是否允许排队？一个请求最多跑多久？失败是否重试？如果 RAG 每次还要跑嵌入、向量检索和重排，这些也要算入延迟。

第一版可以给自己定一个明确目标：例如 5 个内部用户，单请求 8K 到 16K 上下文，首 Token 延迟 3 秒内，普通问答 20 秒内结束，每分钟 20 次请求以内。这个目标比“我要搭一个生产级平台”更容易落地。之后再根据日志扩容。

CPU 也不是完全不能用。小模型、嵌入、离线批处理、低频任务可以跑 CPU。Apple Silicon 的统一内存和 Metal 支持让 Mac 也适合很多本地 AI 试点。但如果要多人同时用大模型，GPU 服务器仍然更稳。

7. 统一模型网关：第一天就该有

很多团队早期让业务代码直接调用 Ollama、vLLM 或某个云模型。这样开发快，但后期会很痛：换模型要改业务，统计成本很难，超时重试散落各处，安全策略也不统一。

建议第一天就加一层模型网关。它可以很薄，但要承担几个职责。

第一，统一接口。上层只知道 chat、embeddings、rerank、structured、vision 等能力，不关心底层是 Ollama 还是 vLLM。

第二，统一模型路由。普通问答走本地小模型，复杂任务走本地大模型或云模型，嵌入走专用嵌入模型。路由策略可以从配置开始，不需要一开始就智能化。

第三，统一安全。模型网关不要接收前端直接传来的任意系统提示。系统规则、工具清单、输出 schema 应由后端构造。

第四，统一观测。每次调用记录模型名、版本、输入 Token、输出 Token、耗时、错误、重试次数。没有这些数据，就无法判断哪个模型真正好用。

第五，统一降级。模型不可用时，可以切备用模型、返回排队状态、提示人工处理，而不是整个应用崩掉。

模型网关不必复杂。一个后端模块、一组配置和几个适配器就能起步。关键是把模型后端从业务逻辑中解耦出来。

8. 知识库：文档不是直接扔给模型

本地 AI 最常见的生产场景是内部知识问答。很多失败案例都从“把文档直接塞给模型”开始。文档要进入知识库，至少经过解析、清洗、切块、嵌入、索引、权限标注和更新管理。

解析要保留结构。标题、章节、段落、表格、列表、代码块、图片说明、页码都可能影响答案。如果把 PDF 解析成一团乱文本，后面的向量检索很难补救。

切块要按语义，而不是固定每 500 字硬切。政策文档适合按条款切，技术文档适合按标题和代码块切，会议纪要适合按议题切，表格适合转成行级或主题级片段。每个片段要带来源信息：文件名、章节、页码、更新时间、文档版本、权限标签。

清洗不是删得越多越好。页眉页脚、重复版权声明、导航菜单、无意义空白可以去掉；但编号、单位、限制条件、例外条款不能丢。很多业务问答错在把“例外情况”清洗掉了。

更新也要设计。文档被替换后，旧向量要删除或标记失效；同一文档多版本要能区分；知识库要支持增量索引；失败任务要能重跑。否则模型会引用过期政策。

9. 向量库怎么选

第一套本地栈可以从四类向量存储中选。

pgvector 适合已经使用 PostgreSQL 的团队。它把向量检索放进熟悉的关系数据库里，权限、备份、事务、业务表关联都方便。规模不大时，pgvector 很务实。它支持 HNSW、IVFFlat 等索引方式，也能配合 SQL 做 metadata 过滤。

Qdrant 是专门的向量数据库，过滤能力、集合管理、payload 设计、相似度搜索体验都比较好。它适合希望把向量检索作为独立服务管理的团队。

Milvus 面向更大规模向量检索和复杂索引场景，生态完整，适合数据量更大、检索吞吐更高的团队。但第一版引入时要考虑运维复杂度。

Chroma 更适合快速原型和轻量应用，开发体验简单。对个人项目或早期试验很方便，但生产使用要关注持久化、并发、权限和运维方式。

选型时不要只看“哪个最强”。看你的现状：团队会不会运维 PostgreSQL？数据量是十万片段还是上亿片段？是否需要复杂过滤？是否要多租户？备份恢复怎样做？权限标签能不能进入检索过滤？第一套系统最怕为了未来规模引入当前运维不了的复杂度。

10. 检索链路：向量召回只是开始

一个生产 RAG 链路通常包含：查询改写、召回、过滤、重排、去重、上下文组装、答案生成、引用校验。

查询改写用于把用户口语问题变成更适合检索的查询。例如用户问“上次那个报销规则还算吗”，系统可能需要结合会话状态改写成“公司差旅报销规则 最新版本 生效日期”。但查询改写不能改变用户真实意图，改写结果也要记录。

召回可以多路并行。向量召回找语义相近内容；全文检索找精确关键词、编号、人名、产品名；metadata 过滤按部门、权限、时间、版本筛选；图谱或关系表可以处理组织结构、产品层级和流程依赖。

重排用于在候选片段中选出最相关的材料。它能缓解向量召回“看起来像但不回答问题”的问题。很多时候，召回 30 个、重排取 5 个，比直接向量取 5 个稳定。

上下文组装要控制顺序和密度。可以按相关性、来源权威性、时间新旧和章节结构排序。相邻片段来自同一文档时，可以合并。互相冲突的片段要同时呈现给模型，并要求说明冲突和依据。

引用校验是生产 RAG 的底线。答案中说出的关键事实，应当能对应到检索片段。做不到时，宁可回答“资料中没有找到明确依据”，也不要编。

11. 工具调用：把业务能力包装成可控工具

本地 AI 栈一旦接入工具，就从“问答系统”进入“行动系统”。这时风险也会放大。

工具应当由后端服务包装，不要让模型直接拼 SQL、直接访问文件系统、直接请求内网 URL 或直接运行 shell。模型只负责选择工具和生成参数，工具服务负责权限、参数校验、执行和审计。

工具可以按风险分级。0 级是纯计算工具，例如格式转换、日期计算。1 级是只读查询，例如查知识库、查订单状态。2 级是低风险写入，例如创建草稿、生成待办。3 级是有业务影响的写入，例如发送邮件、修改订单、提交审批。4 级是高风险操作，例如删除数据、执行部署、付款、变更权限。

不同级别要有不同策略。0 到 1 级可以自动执行，但要记录日志。2 级可以自动执行或弱确认。3 级必须给用户展示将要执行的内容并确认。4 级需要更严格的审批、权限和回滚方案。不要把“请确认”只写在提示词里，确认必须由产品和后端流程实现。

工具 schema 要短而清晰。参数类型、枚举、必填项、默认值都要明确。不要让模型传入自由文本再由工具猜。工具返回值也要干净：给模型业务需要的信息，不要返回密钥、内部堆栈、数据库字段全集和无关日志。

12. 权限边界：模型不是用户，也不是管理员

生产 AI 系统里最容易混乱的问题是权限主体。模型不是用户，模型也不是管理员。模型只是代表当前用户在当前会话中提出建议或请求工具执行。真正的权限判断必须基于用户身份、组织策略、资源标签和工具风险等级。

至少要有三层权限。

第一层是用户访问权限。用户能看哪些文档、哪些项目、哪些客户、哪些系统。RAG 检索必须在召回前或召回时过滤权限，不能先检索全部再指望模型不说。

第二层是工具执行权限。用户能调用哪些工具、能对哪些资源执行什么动作。即使模型生成了正确参数，如果用户没有权限，工具也必须拒绝。

第三层是模型上下文权限。哪些信息可以进入模型输入，哪些信息只能在工具层判断，哪些信息要脱敏。系统提示、密钥、内部策略不应随便进入可被模型复述的上下文。

还要注意代理链路。用户让 AI “帮我把这个文件发给同事”，AI 调用邮件工具时，发件人是谁？审批记录是谁确认的？失败重试会不会重复发送？这些都不是模型能独自负责的事情。

13. MCP 与工具生态：标准化有价值，但别裸奔

Model Context Protocol 把模型应用与工具、资源、提示之间的连接标准化。它的价值在于让不同客户端和服务端通过统一协议交换能力，减少每个应用单独集成工具的成本。对本地 AI 来说，MCP 很适合把文件、数据库、内部系统、浏览器、开发工具等能力接入智能体。

但标准化不等于自动安全。MCP server 暴露了什么工具，工具有没有认证，资源有没有权限过滤，客户端如何确认危险操作，日志怎样记录，这些仍然需要你设计。不要把随便下载的工具服务接入生产环境，更不要让它拥有超出任务所需的文件或网络权限。

一个稳妥做法是按环境分组：开发环境可以接入代码搜索、测试运行、本地文件读写；办公环境可以接入日历、邮件草稿、知识库；生产环境只接入经过审计的只读工具和有限写工具。每个 MCP server 都应有最小权限、版本记录和启停控制。

14. 上下文工程：生产栈里的中枢

模型、向量库、工具都准备好了，并不代表系统会聪明。真正把它们组织起来的是上下文工程。

一个本地 AI 请求的上下文可以包括：系统边界、用户目标、用户身份摘要、会话状态、检索证据、工具清单、工具结果、输出格式、风险提示。每一块都要有来源和优先级。

系统边界要短而硬，说明这个应用服务什么场景、不能做什么、遇到高风险操作怎样处理。用户目标要来自当前请求，不要让模型从很长历史里猜。检索证据要带来源，不可信文档中的内容不能当指令。工具结果要和用户输入分开，避免外部系统返回的文本诱导模型越权。输出格式要面向最终用户，不要露出内部字段、调试名和工具堆栈。

上下文还要预算。不要把全部历史、全部工具、全部检索片段都塞进去。第一版可以建立规则：保留最近几轮对话；远期历史摘要；检索片段最多 5 到 8 个；工具说明按任务动态选择；输出预留足够 Token。随着日志积累，再调整预算。

15. 安全：从提示注入开始，但不能停在那里

本地 AI 也会遭遇提示注入。攻击内容可以来自网页、PDF、邮件、聊天记录、知识库文档、代码注释、工具返回值。攻击者会让模型忽略系统规则、泄露隐藏提示、调用危险工具或输出敏感数据。

防护要分层。首先，外部内容都标记为不可信数据，而不是指令。其次，系统指令、用户请求、检索材料、工具结果在上下文中分区。再次，工具执行层强制权限，不因为模型“认为可以”就执行。最后，对高风险输出和动作设置人工确认。

除了提示注入，还要关注敏感信息泄露、过度代理、供应链风险、模型文件来源、向量库越权、日志泄露和不安全插件。下载模型要看来源和许可证；运行第三方工具要限制文件和网络权限；日志里不要保存明文密钥和过多个人信息；向量库备份也要按敏感数据管理。

OWASP LLM Top 10 对这些风险有系统分类，NIST AI RMF 提供治理框架。不要把它们当合规文档束之高阁，第一套本地栈至少应落实四个动作：最小权限、危险操作确认、敏感日志脱敏、运行链路可追溯。

16. 可观测性：没有 trace 就没有生产

AI 应用的 bug 很多不是传统异常，而是“回答不对”“引用错了”“没按权限拒绝”“工具调错了”“同样问题今天变差了”。没有 trace 很难定位。

建议每次请求记录以下信息：请求 ID、用户 ID 或脱敏主体、模型名、模型版本、输入 Token、输出 Token、延迟、检索查询、命中文档 ID、进入上下文的片段、工具调用名称、工具参数摘要、工具结果摘要、错误码、最终回答、用户反馈。

智能体任务还要记录步骤：计划、行动、观察、状态更新、停止原因。这样当用户问“它到底有没有查最新文档”时，你能回答；当工具误操作时，你能知道谁确认、传了什么参数、执行结果是什么。

日志要分级。调试环境可以保留更多上下文；生产环境要脱敏和限期保留；高敏工具要单独审计。观测不是把所有隐私倒进日志，而是留下足以追责和改进的证据。

17. 评测：用自己的任务压模型

本地 AI 栈搭起来后，最容易犯的错是用几句闲聊判断效果。生产评测应该来自真实任务。

可以先建一个小评测集：内部制度问答 20 条，技术文档问答 20 条，长文摘要 10 条，工具调用 10 条，结构化输出 10 条，权限拒绝 10 条，提示注入 10 条。每条样本记录期望答案、可接受来源、必须拒绝的行为、格式要求和风险等级。

评测要拆链路。RAG 错了，先看正确文档有没有召回；召回了再看重排是否排序靠前；进了上下文再看模型是否引用；模型答错再看提示和模型能力。工具调用错了，先看工具选择，再看参数，再看权限校验，再看执行结果。

不要只比较模型分数，也要比较成本和延迟。一个模型答案略好但慢三倍，可能不适合高频客服；一个小模型能稳定做分类和路由，就不必让大模型处理所有请求。

18. 部署方式：开发机、内网服务器、容器和队列

第一套本地 AI 栈可以从开发机起步，但要尽快迁移到稳定运行环境。开发机适合试验，内网服务器适合团队共享，容器适合部署一致性，任务队列适合长任务和批处理。

模型服务建议独立进程运行。不要把大模型加载在普通 Web 后端进程里，否则重启、内存泄露、并发阻塞都会互相影响。AI 后端通过 HTTP 或本地网络访问模型服务。

长任务要队列化。文档入库、批量嵌入、长报告生成、多步智能体执行，都不适合同步阻塞请求。队列任务要有状态：等待中、处理中、需要确认、失败、完成。用户界面展示进度，而不是让浏览器一直等。

配置要版本化。模型名、上下文长度、温度、检索 topK、重排开关、工具权限、系统提示版本，都应该可记录、可回滚。否则一次“顺手调参”就可能让线上效果变差却找不到原因。

备份要覆盖知识库和向量库。原始文档、解析结果、向量索引、metadata、工具审计日志都可能需要恢复。不要只备份代码。

19. 一条可落地的搭建顺序

第一步，确定场景。不要泛泛地做“企业 AI 助手”。选一个可验收场景，例如“内部制度问答带引用”“客服知识库助手”“研发文档问答”“本地日志诊断助手”。

第二步，选模型后端。个人或小团队先用 Ollama；需要更底层控制用 llama.cpp；需要并发推理用 vLLM。先保证 API 能稳定返回、能流式输出、能记录耗时。

第三步，做模型网关。统一聊天和嵌入接口，记录模型版本、Token、错误。即使只有一个模型，也先走网关。

第四步，搭知识库。解析十到五十份真实文档，按结构切块，写入 pgvector 或 Qdrant，保留来源和权限标签。

第五步，做 RAG 问答。查询、召回、重排、组装上下文、生成答案、显示引用。先把引用准确做稳，再追求回答漂亮。

第六步，接一个只读工具。比如查询工单、查订单、查本地配置。工具返回值要精简，调用要留日志。

第七步，接一个需要确认的写工具。比如创建草稿或待办。前端展示模型准备执行的内容，用户确认后后端执行。

第八步，加评测和观测。固定评测集、请求 trace、错误面板、人工反馈入口。此时才算从演示走向生产雏形。

20. 一个社区版最小配置建议

如果只是给小团队搭第一版，可以考虑这样开始。

硬件：一台内存较大的 Mac、Linux 工作站或带消费级 GPU 的服务器。先服务 3 到 10 个内部用户，不承诺大规模并发。

模型：一个中文能力较好的 7B 到 14B 指令模型作为常驻助手；一个嵌入模型做知识库；必要时加一个重排模型。复杂任务暂时允许手动切换更大模型或云模型。

推理：Ollama 起步，保留切换到 vLLM 的接口空间。模型网关用后端代码封装，不让业务直接依赖 Ollama 特有响应。

向量库：已有 PostgreSQL 就用 pgvector；没有数据库负担且想独立管理，就用 Qdrant。原始文档和切块结果都要保存，不要只保存向量。

后端：一个负责认证、会话、RAG、工具和日志的服务。工具调用必须从这里走。

前端：简洁聊天界面，但必须显示引用、工具确认、任务状态和失败原因。不要把内部字段、调试日志、模型原始 JSON 暴露给最终用户。

安全：默认只读；写操作确认；工具参数白名单；日志脱敏；知识库按用户权限过滤。

验收：至少 50 条真实评测样本；RAG 答案可追溯；工具调用可审计；模型服务重启后应用能恢复；知识库可重新索引。

21. 常见坑和修法

坑一：只搭聊天，不搭知识库。结果模型会凭训练知识回答内部问题。修法是先做 RAG，并要求答案带来源。

坑二：只做向量检索，不做权限过滤。结果用户可能检到不该看的文档。修法是权限标签进入 metadata，并在召回阶段过滤。

坑三：工具太强，确认太弱。结果模型误判就可能真实改数据。修法是工具分级、后端授权、前端确认和审计。

坑四：模型直接返回给用户内部错误。结果界面出现堆栈、字段名、服务名。修法是错误分层，对用户只显示可理解的失败状态，对工程日志保留细节。

坑五：没有固定评测集。结果每次换模型都靠感觉。修法是维护小而真实的样本集，持续跑。

坑六：上下文塞满历史。结果慢、贵、还容易偏题。修法是保留近期关键轮次，远期摘要，检索材料去重。

坑七：只备份向量库。结果重建困难。修法是同时保存原始文件、解析文本、切块 metadata、嵌入模型版本和索引配置。

坑八：把本地服务暴露到公网。很多本地推理服务默认没有强认证或面向内网使用，公网暴露会带来严重风险。修法是只走内网、VPN、反向代理认证或零信任访问，并限制来源。

22. 从第一套栈到长期平台

第一套生产栈稳定后，可以逐步升级。

模型层可以增加多模型路由：小模型做意图识别和分类，大模型做复杂推理，嵌入模型专门服务检索，多模态模型处理图片和 PDF 截图。推理层可以从单机 Ollama 升级到 vLLM 集群，加入队列、缓存和自动扩缩。

知识层可以增加混合检索、重排、权限继承、文档版本对比、知识过期提醒和引用可信度。工具层可以从几个只读 API 扩展到审批流、工单流、开发工具和运营工具，但每增加一个工具都要评估风险等级。

智能体层可以加入计划器、任务状态机、人类确认、长期记忆和多代理协作。这里要格外克制：智能体越复杂，越需要观测和测试。不要为了“像智能体”而牺牲可控性。

治理层可以增加模型评测面板、成本面板、质量反馈、红队测试、权限审计和数据保留策略。到这个阶段，本地 AI 就不只是一个项目，而是组织内部的 AI 基础设施。

23. 最后：先把链路做真

本地 AI 第一套生产栈的标准，不是页面多酷，也不是模型参数多大，而是链路是否真实。

用户问内部问题时，系统有没有真的检索有权限的文档？答案有没有引用？模型不知道时会不会承认不知道？工具调用前有没有检查权限？写操作有没有确认？失败有没有可理解状态？工程团队能不能根据 trace 找到问题？换模型后有没有评测对比？

这些问题都回答得上，哪怕第一版只服务十个人，也已经比一个漂亮聊天壳更接近生产。相反，如果只是把本地模型接到输入框，不能证明资料来源、不能控制工具、不能追踪错误，就还只是演示。

本地 AI 的长期价值来自可控和可演进。第一套栈要小而完整：模型能换，知识可查，工具受控，权限清晰，日志可追，评测能跑。先把这条链路做真，再谈更大的模型、更长的上下文和更复杂的智能体。

24. 权限矩阵：第一版也要写清楚

很多本地 AI 项目一开始只给内部同事使用，于是觉得权限可以以后再补。实际风险正好相反：内部系统往往接了更多文档、文件夹、数据库和脚本，一旦模型工具没有边界，误操作和越权读取更容易发生。

第一版可以先做一张简单权限矩阵。角色分成普通成员、项目管理员、知识库维护者、系统管理员。资源分成公开知识、部门知识、项目知识、个人文件、业务记录、系统配置。动作分成读取、索引、修改、删除、导出、调用工具、批准写操作。每个格子写清楚是否允许、是否需要确认、是否记录审计。

例如普通成员可以读取公开知识和自己所在项目的知识，但不能索引新文档；知识库维护者可以上传和更新文档，但不能调用业务写工具；项目管理员可以批准项目内的低风险写操作；系统管理员可以管理模型和工具配置，但不默认拥有查看所有业务内容的权限。这样设计能避免“管理员就是全知全能用户”的粗糙做法。

权限矩阵要落到检索和工具两条链路里。检索时，用户身份和资源标签必须参与过滤，不能先召回全部片段再让模型自觉隐藏。工具执行时，后端根据用户身份、工具风险等级和资源范围判断是否允许。模型生成的理由不能替代权限判断。用户说“我老板同意了”也不能替代系统里的审批记录。

25. 实操验收：怎么判断这套栈能交给团队用

交付第一版前，建议做一次端到端验收，而不是只看服务是否启动。

第一组验收是知识问答。选十个只有内部文档能回答的问题，要求答案带来源；选五个资料里没有答案的问题，要求系统明确说没有依据；选五个旧版和新版冲突的问题，要求引用新版；选五个跨部门权限问题，确认无权限用户检索不到受限资料。

第二组验收是工具调用。用只读工具查询一条真实记录，检查回答是否来自工具结果；让模型尝试查询无权限记录，检查是否被拒绝；创建一个草稿类写操作，检查确认前不会执行；确认后检查外部系统是否真的出现记录；重复提交同一请求，检查是否有幂等保护。

第三组验收是故障场景。停掉模型服务，看前端是否显示可理解失败；让向量库返回空结果，看模型是否停止编造；让工具超时，看任务状态是否可恢复；把一段提示注入文本放进知识库，检查系统是否仍按工具权限执行；重启后端，检查未完成任务是否能继续或明确失败。

第四组验收是观测。随机抽一条请求，看能否找到模型版本、检索片段、工具调用、耗时和最终回答；随机抽一个失败，看能否定位是模型失败、检索失败、工具失败还是权限拒绝。如果这些证据找不到，就说明还不能算生产栈。

26. 排障手册：回答错了先查哪一层

本地 AI 系统出错时，不要第一反应换模型。先按链路排查。

如果答案缺少关键事实，先看检索有没有召回正确片段。没有召回，就查文档是否入库、切块是否完整、嵌入模型是否适合中文、查询是否需要改写、metadata 是否把正确文档过滤掉。召回了但排序靠后，就加重排或调整混合检索。片段进了上下文但模型没用，再改提示和模型。

如果答案引用错误，先看引用 ID 是否在上下文组装时丢失，是否把多个片段合并后来源混乱，是否允许模型自由编造引用。引用应该由系统基于片段 ID 渲染，模型只选择或说明依据，不应凭空生成链接。

如果工具调错，先看工具描述是否重叠、参数 schema 是否太宽、工具数量是否一次暴露太多。再看后端是否做了权限和参数校验。工具层必须能拒绝危险调用，而不是把错误调用执行完再解释。

如果响应慢，先拆延迟：模型首 Token、生成总时长、嵌入耗时、向量检索、重排、工具接口、网络传输。长上下文和长输出通常是大头，重排和工具超时也常见。不要盲目加机器，先看是否塞入了过多历史和重复片段。

如果用户说“同样问题昨天能答今天不能”，要查模型版本、提示版本、知识库版本、索引时间、检索 topK、工具返回和权限标签有没有变化。生产栈的配置必须可追踪，否则问题会变成玄学。

27. 一套可执行的首月迭代节奏

第一周只做链路，不追求完美。跑通模型网关、一个生成模型、一个嵌入模型、一个向量库、十份真实文档和基础问答页面。验收标准是能回答、能引用、能记录日志。

第二周做质量。优化文档解析和切块，加入权限标签，建立五十条评测样本，引入混合检索或重排。验收标准是核心问题引用命中明显提升，错误问题能承认不知道。

第三周做工具。接入一个只读业务工具和一个草稿类写工具，完成工具分级、确认页、审计记录和失败处理。验收标准是工具结果可追溯，写操作确认前不会发生真实变化。

第四周做运营。补齐监控、备份、模型版本记录、知识库重建流程、用户反馈入口和排障手册。验收标准是服务重启不丢关键数据，模型或知识库升级后能通过评测比较效果。

这个节奏的重点是每周都留下可运行系统，而不是堆一堆未来架构图。第一套本地 AI 生产栈最怕目标过大、链路不真。按月推进，先让小团队每天用，再从真实反馈里扩展。

参考资料

1. Ollama Documentation - 本地模型运行、API、结构化输出、嵌入和工具调用相关文档。
2. llama.cpp GitHub Repository - GGUF、量化、本地推理和 server 模式的核心项目文档。
3. vLLM Documentation - 高吞吐推理、OpenAI 兼容服务、PagedAttention 和服务端部署资料。
4. LM Studio Docs - 桌面本地模型管理和 OpenAI 兼容本地服务文档。
5. LocalAI Documentation - OpenAI 兼容本地推理网关和多后端部署资料。
6. Qdrant Documentation - 向量数据库、payload 过滤、混合检索和部署文档。
7. Milvus Documentation - 大规模向量数据库、索引、混合检索和重排相关文档。
8. pgvector GitHub Repository - PostgreSQL 向量扩展，包含 HNSW、IVFFlat 和相似度查询说明。
9. Chroma Documentation - 轻量向量数据库和嵌入应用开发文档。
10. OpenAI Platform Docs：Function calling - 工具调用和参数 schema 的官方说明。
11. OpenAI Platform Docs：Embeddings - 嵌入模型和语义搜索的官方说明。
12. OpenAI Platform Docs：Structured Outputs - 使用 JSON schema 等方式约束模型输出的资料。
13. Model Context Protocol Specification - MCP 工具、资源、提示和授权相关规范。
14. OWASP Top 10 for LLM Applications 2025 - LLM 应用提示注入、数据泄露、供应链和工具风险分类。
15. NIST AI Risk Management Framework - AI 风险管理和生成式 AI 治理资料。
16. Hugging Face Transformers Documentation - 模型、分词器、推理和开源生态文档。
17. Hugging Face Text Embeddings Inference - 嵌入模型服务化和高性能推理资料。
18. OpenTelemetry Documentation - 分布式追踪、指标和日志的通用可观测性文档。
19. Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks - RAG 代表论文，说明检索与生成结合的基本思路。
20. ReAct: Synergizing Reasoning and Acting in Language Models - 结合推理和行动的智能体方法论文。