企业官网建设流程全解析

1. 为什么我要把智能体“困”在本地：一条反主流的选型路线

1.1 你看到的很多“智能体”，其实只是套了层网页壳

先说点大实话。市面上能叫得出名字的智能体平台，绝大多数都是“云端套壳”：你点两下鼠标，填个 API Key，App 内部帮你把模型请求转发到服务商的接口，再包装出一个像模像样的对话界面。这种方案确实快，半天就能跑出 demo，但一旦业务场景里有数据出域限制、私有化交付要求，或者干脆就是行业客户的内网环境，云端方案直接出局。

我手里的这个内部数据问答项目就是典型：数据不能出内网，文档不能传第三方服务器，模型可以不用最顶级的，但必须本地跑。刚开始我还抱着一丝侥幸，想用本地小模型 + 云端大模型混编，结果越测越不对劲——接口延迟、鉴权、限流每个环节都在提醒我，还不如踏踏实实把整个链路放在本地。

于是我把目光放到了本地部署这条路线上。经过几轮选型调研，最终确定用 ModelEngine 做推理与模型调度层，Nexent 做智能体框架层。这两个东西的组合，让我在不出内网的前提下，跑起了一个具备多工具调用、多 Agent 协作能力的智能体。这篇记录不是官方教程翻译，而是我从零开始部署、配置、踩坑、调优的全过程复盘，希望能让跟我有类似需求的人少走几个礼拜弯路。

1.2 ModelEngine 和 Nexent 的定位，以及我选它的原因

先解释一下这两个组件分别干什么。ModelEngine 是一个本地大模型推理调度引擎，它把模型服务、上下文窗口、并发策略、量化参数统一管起来，对外暴露兼容 OpenAI API 协议的访问入口。简单说，它就是智能体的“发动机舱”，负责让模型真正跑起来，并且让上层框架不用关心底层是 vLLM、Ollama 还是其他推理后端。

Nexent 则是典型的智能体框架，负责 Agent 循环、工具调用、任务拆解和多轮对话管理。它本身并不直接加载模型权重，而是通过 HTTP 请求去调用 ModelEngine 暴露的接口。用生活化的比喻：ModelEngine 是发电厂，Nexent 是配电系统，智能体应用是用户家里的电器。发电厂发出电，配电系统决定把电送到哪个房间，电器负责执行具体任务。

我选择这套组合的原因，一是两者分工足够清晰，模型层和逻辑层互相解耦；二是 Nexent 支持相对标准的工具调用协议，后面挂企业内部系统时不用为适配不同模型写一堆硬编码；三是 ModelEngine 天生支持多模型挂载，我可以把 7B 的小模型和 14B 的大模型同时挂在线上，按任务难度灵活路由，这在内存有限的工作站上非常实用。

1.3 这套方案适合谁，不适合谁

必须先把话说明白：如果你只是想快速做一个演示用的 Demo，三天后给领导看个 PPT，那直接上云端 API，别折腾本地部署。本地部署的最大代价不是硬件成本，而是“工程成本”。模型下载、驱动匹配、框架配置、工具调试、内存调优，任何一步出问题，你都要自己面对。

这套方案真正适合三类人：一是有数据合规要求，模型和文档都不允许出内网；二是有长期项目规划，智能体会持续迭代，需要一套可复用的框架；三是硬件尚可，拥有一张 24GB 显存以上显卡的个人开发者或小型团队。

如果你是学生党，手上只有一张 8GB 显存的卡，也别灰心，可以跑 7B 或 3B 量化模型，核心链路是一样的。下面我会按我实际部署时的顺序来讲，每一步都尽量给出具体的配置和参数。

2. 部署前的家底盘点：硬件、系统和依赖清单

2.1 我的机器配置和“勉强能跑”的预判

先交代我的运行环境。我用的是一台双路工作站，系统 Ubuntu 22.04，CPU 是 64 核的 EPYC 处理器，内存 128GB，显卡是 A6000 48GB。显存是部署智能体最重要的硬性指标，因为它直接决定你能跑多大的模型、多大的上下文窗口。

48GB 这个级别，跑 14B 量化模型是比较舒服的，模型权重占 16GB 左右，剩下的显存可以用来做 KV Cache 和多请求并发。如果是 24GB 显存，跑 7B 量化模型没问题，跑 14B 就得压缩上下文窗口。8GB 显存则建议把目标定在 3B 到 7B 的小模型，配合量化把显存占用控制在 6GB 以内。

另外一个经常被忽略的指标是内存。模型推理时的 CPU 内存开销很容易被低估，vLLM 的调度器、tokenizer、预加载的数据，跑 14B 模型时我观察到约 16GB 的 CPU 内存占用。128GB 内存对我来说绰绰有余，但如果你是 32GB 内存的机器，建议关掉浏览器里几十个标签页，并且不要同时跑多个大模型服务。

2.2 依赖安装顺序：为什么先装驱动再装 Python 库

依赖安装顺序极其重要，我身边不止一个人因为贪快把顺序搞反了，最后全部重装。正确的顺序是：驱动程序 → CUDA Toolkit → Python 环境 → 推理引擎 → 智能体框架。

第一步先确认驱动。运行nvidia-smi，看右上角显示的 CUDA 版本。比如我这边显示的 Driver Version 是 550.54.14，CUDA Version 是 12.1，那就说明驱动层面已经支持 CUDA 12.1 及以下版本。如果这里显示的版本过低，后面 vLLM 和部分深度学习库都会报 CUDA 初始化失败。

第二步创建 Python 隔离环境。我用的是 Miniconda，命令非常简单：

conda create -n modelengine python=3.10 -y conda activate modelengine

这里必须强调：如果你不想把系统 Python 环境搞成一锅粥，一定要用虚拟环境。我见过有人直接用系统 Python 装 vLLM，结果把系统自带的依赖搞坏，最后重装系统的惨案。Python 3.10 是目前兼容性最好的版本，多个库的适配都很完善，3.11 和 3.12 在部分深度学习库上依然可能有编译问题。

第三步安装推理引擎。我的首选是 vLLM，原因后面详述。安装命令可以用预编译的 wheel 包，也可以用源码编译，但源码编译耗时很长，我建议非特殊需求一律用预编译版本。

2.3 模型选型：14B 量化版是我的性价比甜点

智能体的智商上限由模型决定，所以模型选型是部署前最重要的事。我这次选的是 Qwen2.5-14B-Instruct，量化格式 AWQ，权重文件约 16GB。为什么选 14B 而不是 7B 或 70B，理由有三：

第一，7B 模型在复杂工具调用场景下，经常出现“听不懂指令、不会格式化 JSON”的问题。智能体框架要求模型输出结构化的工具调用指令，7B 模型对这种格式的输出能力明显弱于 14B。第二，70B 模型效果肯定最好，但一次推理就要占用约 140GB 显存，我这张 48GB 的卡完全跑不动，除非上多卡方案。第三，14B 量化模型在显存占用、推理速度和能力之间取得了最佳平衡。

我还额外准备了一个 DeepSeek-R1-Distill-Qwen-7B 作为轻量任务模型，负责摘要、格式化、简单问答这类低难度任务。这个 7B 模型只占约 8GB 显存，可以常驻。后面 ModelEngine 的多模型路由就是为这种场景服务的。

下表是我当时整理的模型选型对比，给后来人一个参考：

强调一句：模型仓库里的名字、量化格式、上下文长度一定要记准。后面配置 ModelEngine 时，模型名的大小写和连字符都要严格一致，否则会返回 404，这个坑我后面细讲。

3. 从拉模型到跑通第一次对话：安装全程实录

3.1 模型服务先行：我先用 Ollama 起步，再迁到 vLLM

模型服务是整条链路的底座，必须最先跑通。我最初用的 Ollama，因为它一个命令就能拉起模型服务，非常方便：

ollama pull qwen2.5:14b ollama serve

实测下来，Ollama 的部署门槛确实低，但它有几个问题：并发处理能力有限，当智能体框架同时发起多个请求时，请求会排队；上下文管理的弹性较差，长上下文的性能不理想。所以我把长期方案定在 vLLM。

vLLM 是专门为推理优化设计的引擎，支持 PagedAttention、连续批处理、量化推理加速等功能。启动命令如下：

conda activate modelengine vllm serve /models/Qwen2.5-14B-Instruct-AWQ \ --quantization awq \ --max-model-len 32768 \ --gpu-memory-utilization 0.90 \ --port 8000

启动成功的标志是日志里出现Application startup complete和一串模型注册信息。此时可以用 curl 验证服务是否正常：

curl http://127.0.0.1:8000/v1/models

你会看到一个模型列表，里面包含服务端实际注册的模型名。记住这个名字，后边配置要完全照抄。

3.2 ModelEngine 的安装与注册：假装自己是 OpenAI

ModelEngine 本身不直接跑模型，它是个中转调度层。安装方式比较简单：

pip install modelengine modelengine init

初始化之后，它会生成一个modelengine.yaml配置目录。核心配置就是把 vLLM 的地址、模型名、上下文长度注册进去：

models: qwen2.5-14b: provider: vllm base_url: http://127.0.0.1:8000/v1 api_key: local-dummy-key context_window: 32768 deepseek-r1-7b: provider: vllm base_url: http://127.0.0.1:8001/v1 api_key: local-dummy-key context_window: 32768

看到api_key你可能疑惑，本地服务为什么还要 key？原因很现实：一些客户端库会强制校验这个字段，如果不填，请求还没发出就被拒了。填一个占位符即可，实际转发给 vLLM 时它并不校验。

启动 ModelEngine 后，它会在默认端口监听，并向外暴露 OpenAI 兼容的接口。此时智能体框架就可以通过统一的地址访问所有模型。这一步的本质，就是给上层应用一个统一的接入面，避免多个模型各自为政。

3.3 Nexent 框架的初始化：改四个配置就能动

ModelEngine 跑起来以后，轮到 Nexent 登场。安装依然简单：

pip install nexent nexent init my-agent

初始化完成后，你会看到如下目录结构：

my-agent/ ├── agents.yaml ├── tools/ ├── memory/ ├── logs/ └── run.py

agents.yaml是核心配置文件，里面需要指定模型引擎地址、角色定义、工具目录路径。我贴一个最简配置：

agents: main_agent: engine: modelengine model: qwen2.5-14b system_prompt: > 你是一名专业的本地知识库助手， 请根据用户问题，调用合适的工具获取信息， 并给出准确、简洁的回答。 tools_dir: ./tools max_iterations: 8 temperature: 0.3

这里max_iterations尤其重要，它决定了 Agent 在单轮任务中最多能调用多少次工具。如果不设上限，模型可能在某个工具返回异常时陷入死循环，一次对话消耗大量算力。记住这个设计，后面踩坑专门聊。

首次启动前，只需要确认这几个配置：模型引擎地址、模型名、系统提示词、工具目录。其他选项可以用默认值先跑通，后续再优化。

3.4 第一次握手：当我问它“你是谁”

配置完成后，我启动了第一个会话：

nexent run --agent main_agent

刚开始我很忐忑，毕竟模型文件名、注册名、配置名都带大小写和连字符，任何一处对不上都会报错。好在 vLLM 和 ModelEngine 都是标准的 OpenAI 兼容协议，第一次握手很顺利。当我输入“你是谁”时，Agent 正常返回了一段自我介绍，并在日志中记录了一条完整的调用链：用户输入 → 主 Agent 决策 → 不需要工具 → 直接生成回答 → 返回给用户。

这一步的意义不在于回答本身，而是验证了整条链路：HTTP 请求能通、模型能加载、框架能完成推理循环。链路跑通之后，后面所有问题就都变成了“优化问题”，而不是“能不能启动”的问题。

4. 踩坑实录：六个让我差点想放弃的问题

4.1 OOM 和 CUDA 版本错位：不是你卡了，是根本不够用

这不是技术选择，而是逼出来的现实。最开始我图省事，直接用系统自带的 Python 环境装了 vLLM 0.6.x，结果启动时直接报错CUDA error: no kernel image is available for execution on the device。这个问题本质是 vLLM 的预编译 CUDA kernel 与我的显卡驱动版本不匹配。vLLM 官方对不同 CUDA 版本提供了不同的 wheel 包，如果装错了，就会在启动时爆出这种令人头大的信息。

解决方案是重新用 conda 创建环境，并且根据驱动对应的 CUDA 版本选择正确的 vLLM 安装包。我当时的驱动是 550.54.14，对应 CUDA 12.1，于是安装时明确指定了vllm-cuda-12.1版本。换完以后，服务能正常启动了，但我又遇到第二个问题：加载模型时显存溢出，进程被 OOM Killer 直接杀掉。

排查过程是这样的：nvidia-smi显示显存占用为 14GB，剩余 34GB，看起来够用，但 vLLM 在初始化时不仅要加载模型权重，还要预留 KV Cache 的空间，默认的gpu-memory-utilization为 0.9 会尝试占满 90% 的显存。我这张卡上还有其他服务占着显存，所以必然 OOM。解决办法是把参数调到 0.85，并限制最大上下文长度到 32768：

vllm serve /models/Qwen2.5-14B-Instruct-AWQ \ --quantization awq \ --max-model-len 32768 \ --gpu-memory-utilization 0.85 \ --port 8000

此外还要注意/dev/shm的大小。vLLM 在做分布式推理或启用某些特性时，会大量使用共享内存。在容器环境下，/dev/shm默认只有 64MB，经常导致加载失败。我的做法是启动容器时加--shm-size=16g。这属于不报错但跑不起来的典型案例，网上讨论的人不多，我查了很长时间才找到原因。

4.2 404 模型名：配置文件里的名字要跟服务端一字不差

这个坑是我在配置完 ModelEngine 以后碰到的。明明 vLLM 那边已经正常加载了模型，但智能体一发请求就报错：ModelNotFoundError: model not found。我下意识以为是 ModelEngine 和 vLLM 之间的协议没对齐，折腾了半天才发现，问题出在名字上。

vLLM 那边注册的模型名是Qwen2.5-14B-Instruct-AWQ，而我配置文件里写的是qwen2.5-14b。OpenAI 兼容接口对模型名的匹配是严格区分大小写的，我顺手写了个小写缩写，结果服务端根本找不到对应的模型。当时那个尴尬，真想找块豆腐撞了。

解决办法很简单：先 curl 一下服务端接口，看看实际模型名，再原样填进配置。我也推荐大家在任何接入 OpenAI 兼容接口的场景下，都先执行这条命令确认一遍，不要去“猜”模型名。实践下来，很多“连接失败”最后都是模型名字符不匹配导致的。

4.3 工具调用死循环：Agent 自己跟自己说话停不下来

当我把外部工具挂上以后，更闹心的事情出现了：Agent 在回答一个简单问题时，反复调用同一个工具，日志里不断出现同一条 tool_call 记录，就是不进入下一步。最夸张的一次，一个“今天天气怎么样”的问题，它把天气工具调了 20 多次，最后我手动中断了进程。

分析日志之后，我发现了根因：工具返回的结果格式不符合框架的预期。Nexent 要求工具返回结构化 JSON，比如{"result": "晴天", "confidence": 0.95}，而我当时最早写的工具返回的是纯文学描述，模型读不懂，于是只能反复尝试调用。

后来我做了两件事。第一，把所有工具的返回格式统一为 JSON。第二，在 Agent 配置里设置合理的max_iterations。即使模型偶尔识别错，也会在达到迭代上限后把已有的部分结果输出，而不是永远耗下去。修改以后，同样的对话在 2 次工具调用内就能完成。这个经验希望大家直接抄走：Agent 配置里的迭代上限一定不要省，宁可在长任务时放宽，也不要让异常情况无限制烧算力。

4.4 多轮对话失忆：上下文窗口被默认参数坑惨了

第三个坑发生在多轮对话测试阶段。我跟 Agent 聊了四五轮之后，它突然把我最早提到的一句话忘记了，答非所问。第一反应是模型本身能力不行，可后来仔细一看，问题出在上下文窗口配置上。

ModelEngine 在接入 vLLM 时，默认的context_window是 4096 tokens。这个数字对于单轮问答绰绰有余，但多轮对话之后，前面的历史消息会被截断，模型自然“失忆”。而我购买的模型权重本身支持 32768 tokens 的上下文，完全能够容纳一个长会话。

修复方式就是前面介绍过的，在modelengine.yaml里显式声明context_window: 32768，同时 vLLM 启动参数里的max-model-len也要一致。修完后，多轮对话 20 轮以上还能准确记住关键信息。

这里有个小技巧：如果你不想让每轮对话都消耗大量 tokens，可以在 Nexent 的记忆模块里设一个历史摘要机制。对话超过一定轮数后，框架自动把之前的对话浓缩成一段摘要，再拼接进上下文。这样既保留关键信息，又控制 tokens 开销。我在连续 50 轮的压力测试里试过，效果很稳定。

4.5 流式输出中断：生成一半连接就断了

智能体最常见的交互模式就是流式输出，打字机一样逐字蹦内容。但我在用 Web 前端对接时，遇到一个诡异的问题：长回答生成到一半，连接突然断开，前端显示“网络异常”。

第一次遇到时我以为是网络问题，检查半天没能解决。后来单独拉了一个测试脚本，用非流式请求跑同样的问题，发现完整回答能正常生成，这才确定问题出在流式传输环节。继续深挖发现，Nexent 这边默认的stream_timeout只有 30 秒，而 14B 模型在复杂推理任务上的生成时间动辄 30 秒以上，只要生成不及时返回一个 chunk，框架就会判定超时，主动断开连接。

解决办法很简单：把stream_timeout调到 120 秒。另外，如果你用 Nginx 做反向代理，也要关闭缓冲，否则流式 chunk 会被 Nginx 积压，前端半天收不到数据：

proxy_buffering off; proxy_read_timeout 300s;

这类问题定位起来特别难受，因为看起来像网络故障，实际上是应用层的超时策略。建议大家把超时时间和流式检测作为基础配置，提前考虑到长文本生成场景。

4.6 端口占用和并发冲突：本地部署的“隐形地雷”

还有一类问题是“重启后一切正常，但只要隔几天再启就怪怪的”。我遇到两次典型情况：一次是 vLLM 的 8000 端口被之前残留的进程占用，新进程起不来；另一次是同时跑两个推理任务，显存分配错乱，导致模型加载失败。

解决思路其实很简单，一是启动脚本里加端口检查，先杀掉旧进程再启动新的。二是用flock防止重复启动：

exec 9>/tmp/modelengine.lock flock -n 9 || { echo "已有实例在运行"; exit 1; }

三是搭建一个简单的健康检查脚本，定期请求/v1/models，如果响应超时就自动重启服务。这套机制看起来不“高级”，但真的能让智能体 7×24 小时稳定运行。本地部署没有云平台那套自动容灾，能靠的只有自己把边界情况处理好。

5. 让智能体真正干活：工具注册与多 Agent 编排

5.1 给 Agent 装上手和脚：工具定义的学问

搞定稳定性问题之后，我开始给 Agent 接入真正的业务工具。Nexent 的每个工具就是一个 Python 文件，放在tools/目录，框架会自动扫描并注册。每个工具可以定义一个 JSON Schema，用来描述工具的用途和参数。

下面是我写的一个“本地文档检索”工具的示例：

from nexent.tools import Tool class SearchLocalDocs(Tool): name: str = "search_local_docs" description: str = "在本地知识库中搜索相关文档。当用户询问制度、规范、手册、指引等内容时，使用该工具。" def run(self, query: str, top_k: int = 5): # 调用本地向量检索服务 return {"result": docs, "total": len(docs)}

这里有个非常关键的细节：description一定要写得足够具体，并且包含“触发条件”。因为 Agent 是依靠描述来判断该不该调用工具的，如果描述太模糊，比如“搜索文档”，模型可能在处理简单问题时也会莫名其妙调它。我试过把“制度、规范、手册、指引”这些关键词写进描述之后，工具调用的准确率提升了近 20 个百分点。这算是一个成本极低、效果显著的优化点。

5.2 多 Agent 编排：主管调度员模式让任务拆解更清晰

当任务越来越复杂，单个 Agent 容易顾此失彼。比如“帮我写一份本地网络的巡检报告，并总结风险点”，它要先搜集数据、再分析风险、再写报告，一个 Agent 身兼数职，效果很拉胯。

我最后采用了“主管 + 专业 Agent”的编排模式：主管 Agent 负责理解用户意图、拆解任务、分发给下游的专用 Agent，然后汇总各部分的输出。配置上大概长这样：

agents: supervisor: model: qwen2.5-14b system_prompt: > 你是任务主管，负责拆解用户请求， 将任务分配给对应的专业Agent，并汇总最终结果。 sub_agents: - research_agent - write_agent - format_agent

每个子 Agent 再各自配置不同的系统提示词和工具集。比如 research_agent 只用检索类工具，write_agent 只用文档生成类工具。这样做的直接收益是：每次调用的上下文更聚焦，模型不必在多个无关工具之间做选择，幻觉和误调用明显减少。

多 Agent 编排也有一点要注意：子 Agent 之间不要互相直接通信，统一由主管中转。否则两个模型来来回回对话，既浪费 tokens，还容易绕进逻辑死胡同。在我的配置里，子 Agent 只能返回结果给主管，一切交互由主管发起。

5.3 记忆与知识库：本地化的最后一公里

智能体要有业务价值，必须能回答业务问题。我的场景是内部制度问答，所以知识库建设是重中之重。做法是：加载内部文档 → 切分文本 → 生成向量索引 → 存入本地向量库 → 通过检索工具接入 Agent。

文档切分的参数直接影响回答质量。我对比几组实验后，用的是 512 token 的 chunk 大小，重叠 64 token。如果切块太大，检索精度下降，容易引入不相关的内容；如果切块太小，上下文碎片化，模型找不到完整答案。512 是在这两者之间比较稳的平衡点。

embedding 模型我用的是 BGE-M3，部署成本低，中文效果不错。这个模型不需要多强的显卡，CPU 跑也没问题。整个知识库检索链路跑通后，我拿 200 个真实业务问题进行测试，准确率从最开始的 50% 提升到了 85% 左右。瓶颈主要在于部分文档本身存在前后矛盾，这不是技术能解决的。

6. 性能调优与资源控制：从“能跑”到“能交付”

6.1 量化、KV Cache 和并发上限之间的关系

部署稳定后，我开始关心资源效率：同样的硬件，能不能承载更多用户、更快响应。这就要弄清显存、KV Cache、并发上限之间的关系。

KV Cache 是推理过程中的缓存数据，大小取决于模型的层数、隐藏层维度和上下文长度。粗略估算公式是：每 token 的 KV Cache 占用等于隐藏层维度 × 层数 × 2 × 2字节（KV 各一份）。拿 Qwen2.5-14B 来算，隐藏层维度 5120，层数 48，那么一个 token 大概占用 5120 × 48 × 2 × 2 ≈ 0.94MB。如果上下文撑到 32768 tokens，单请求的 KV Cache 就是约 30GB，这个数字相当吓人。

所以，长上下文不是免费的。显存不足时，与其硬撑 32K 窗口，不如把上下文窗口降到 8K，同时启用摘要压缩机制。我在实际业务中发现，绝大多数问题用 8K 上下文完全够用。只有长文档分析场景，临时切到 32K 窗口的独立模型即可。这比让所有请求都抢占 32K 的 KV Cache 要高效得多。

6.2 实测数据：不同配置下的响应延迟与吞吐

我把几组关键配置下的实测数据整理成表，方便大家参考：

这里的核心结论是：不要盲目调高并发。vLLM 的连续批处理技术能合并不同请求的推理阶段，但并发数越高，每个请求的等待时间越长。对于办公类问答场景，8 到 12 并发是比较合适的区间，超过后用户体验下降明显。

6.3 日志、监控与故障恢复：没有这些不敢谈“可交付”

如果只是自己玩，日志有没有无所谓。但如果要给企业用，没有监控就等于是裸奔。Nexent 和 ModelEngine 都会在logs/目录下输出结构化的 JSON 日志，包括请求 ID、耗时、模型、token 消耗量和错误码。我后来写了个简单的巡检脚本，每 5 分钟检查一次日志里的错误率，超过阈值就推送通知。

故障恢复方面，我设置了一个开机自启的服务脚本，监控 vLLM 和 ModelEngine 的进程状态。一旦发现进程异常退出，就自动拉起服务。模型服务的重启时间一般在 1 到 2 分钟以内，对于内部工具型智能体来说，这个恢复速度可以接受。

7. 从“能跑”到“能交付”：我踩完坑后留下的几条建议

整套系统上线到现在，大概运行了三个多月，中间迭代了好几个版本。最后分享几条我自己含泪总结的经验，既是对这次项目的收尾，也是给准备入坑的朋友的一点提醒。

第一，第一版务必“小而全”，不要一上来就追求高性能。这是我的最惨痛教训。有一段时间我试图同时跑 3 个模型、挂 10 个工具、配 5 个 Agent，结果每天都有新问题，排查到崩溃。后来痛定思痛，先砍到 1 个模型、3 个工具、1 个 Agent，稳定运行一周后再逐步增加，效率反而更高。

第二，名称规范要统一，尤其是模型名。大小写、连字符、前缀，从头到尾保持一致。这个看似微不足道的细节，直接决定你会不会在 404 上浪费半天时间。

第三，工具描述要给足“触发条件”。工具的 description 里明确写上“什么场景下使用”，能让 Agent 的工具调用准确率提升一大截。这比任何提示词技巧都实用。

第四，KV Cache 和上下文窗口不是越大越好，要结合显存和业务场景来定。先把实际业务里最长的对话测一遍，再决定窗口大小，否则就是纯浪费资源。

第五，本地部署不是一次性项目，它需要持续的观察和调优。我建议至少每隔一周看一次日志，记录异常情况，一点点完善提示词和工具定义。长期积累下来，这套智能体会越用越顺手。

最后，回到最开始的问题：本地部署是不是最优解？对我来说是。它虽然麻烦，却让数据安全、系统可控、成本稳定三者达到了平衡。如果你也想折腾，希望这份记录能帮你省下那些本可以不用踩的坑。