07 - 如何更改或添加 LLM 模型

切换或添加 LLM 模型无需进行任何代理服务器代码更改。所有模型管理均在 Ollama 层完成，受严格的显存（VRAM）限制和三处文档更新规则的约束。更换聊天模型是一个拉取并验证的操作，而更换嵌入模型则会触发知识库的完全重新索引。

apps/agent-server 代码库是刻意构建为与模型无关的。当请求到达时，指定的模型名称会直接透传给 Ollama，无需路由逻辑、硬编码默认值或分支判断。出站请求构建器（位于 agent_loop.py 中的 _prepare_upstream_body()）统一处理模型字段。因此，添加新模型仅需将其拉取到 Ollama 并按名称请求即可——无需对服务器进行任何修改。 唯一的架构例外是嵌入模型（nomic-embed-text），它奠定了整个知识库向量空间的基础；更换它需遵循后文详述的另一种更复杂的流程。

在拉取任何新模型之前，请验证硬件兼容性。这台 Mac 提供77.8 GiB 的可用显存，Ollama 已配置为最多保留两个驻留模型（OLLAMA_MAX_LOADED_MODELS=2）。请使用以下换算公式计算容量：

Model size in GB ÷ 1.074 = size in GiB (the unit that matters for this math)

当前模型搭配兼容性：

添加：

ollama pull <model-name>
ollama list          # Confirm it's there and check its size

300亿至600亿参数（30–60B）的模型通常只需几分钟到超过一小时即可完成下载（最初拉取 gpt-oss:120b 耗时 30–90 分钟）。服务器无需重启；GET /v1/models 会根据需即时查询 Ollama 的实时状态（使用 /api/tags 获取目录，使用 /api/ps 监控驻留内存）。 移除：

ollama rm <model-name>
ollama list          # Confirm it's gone

关键更新规则（同时适用于添加和移除操作）： 您必须更新三个特定位置，否则新模型将默默地失败或引发引用错误。

1. 任何应用的静态模型列表（例如，展示站点的读取器读取的是硬编码表格，而非实时的 Ollama 状态）。
2. SOP-LLM-OPERATIONS.md 的模型表（第 1 部分）——这是跟踪运行哪些模型及其原因的最高权威来源。
3. AGENT_SERVER_GUIDE_v2.md 的日常日志——记录变更的理由，以确保上下文在未来的重新调整中得以保留。

⚠️ 警告： 如果某个脚本、应用默认值或定时任务（cron job）仍然引用已移除的模型名称，Ollama 会抛出错误而非优雅地降级。请先审计隐藏的调用者。

试用流程： 在提升生产环境之前，务必先在 LM Studio 中测试。LM Studio 搭载了苹果的 MLX 运行时框架，据报道在 Apple Silicon 芯片上拥有 10–20% 的速度优势。这使得我们能够在不触碰实时 Ollama 环境的情况下，快速进行侧对侧的质量与速度基准测试。经过验证后，运行 ollama pull 将其拉取到本地，以便通过现有的 OpenAI 兼容端点进行路由。

默认模型与路由：代理服务当前未实施默认模型逻辑或服务器端路由。每个调用者都必须在请求体中明确指定模型。目前尚不存在服务器端自动化功能（例如，“始终将具备视觉能力的请求路由至 VL 模型”或“将简短查询导向更快、更小的模型”）。最接近的先例是 ai_chain.py 客户端路由器，它在调用 API 之前选择模型。实现服务器端路由是一个范围明确的功能扩展（参见 08_Extending_The_Harness_Agent.md）。

三个启动脚本控制着 Ollama 的服务行为。它们的名称仅相差一个单词，这使得很难编辑错误的文件——这三个文件必须保持同步：

• start-ai-stack.command（主要常规脚本）
• start-ai-server.command
• start-ai-server.sh

当前环境默认设置如下：

export OLLAMA_MODELS=/Volumes/AI_DATA/models/ollama
export OLLAMA_MAX_LOADED_MODELS=2
export OLLAMA_KEEP_ALIVE=30m
export OLLAMA_FLASH_ATTENTION=1
export OLLAMA_NUM_PARALLEL=4
export OLLAMA_CONTEXT_LENGTH=65536

要修改这些设置：请对三个脚本进行相同的编辑，运行 stop-ai-stack.command 后跟随 start-ai-stack.command，然后通过以下命令使用实时变数验证：

ps eww $(pgrep -x ollama) | tr ' ' '
' | grep OLLAMA

⚠️ 停机警告： stop-ai-stack.command 还会终止旧版网关，使大约 20 个旧集成短暂下线。请在低流量时段安排服务变更。

未来关注要点：

• 关注 qwen3.6 是否发布官方（非预览版）的 Ollama 标签。
• 留意 Ollama 是否引入原生视频输入支持，以替代当前的 ffmpeg 帧提取临时方案。
• 每 3–6 个月重新评估一次模型阵容。优秀的开源模型不断更新推出；今日的“主力”只是特定时间点的基线，而非永久固定的选项。

nomic-embed-text 负责生成向量，以对齐知识库文档和传入的搜索查询。更换它将立即导致几何对齐失效。所需流程如下：

1. 索引将失效： 旧嵌入使用旧的几何空间；新查询将使用新模型的几何空间。两者在数学上变得不可比。
2. 强制全量重建索引： 运行带强制标志的 kb_sync.py 或 Sync-Knowledge-Base.command，重新处理所有知识库。这是一项缓慢的批量操作，而非增量更新。
3. 更新环境变量： 更改 tools/knowledge_base.py 中的 AGENT_EMBED_MODEL（默认值为 nomic-embed-text），使新查询与重新索引后的模型匹配。

请勿随意更改嵌入模型——它会触发全项目重新索引，应将其视为重大架构操作，而非简单的配置调整。

• 零代码替换： 模型更换无需编辑代理服务器代码；完全依赖 Ollama 的实时状态以及三项关键文档更新。
• 显存硬性限制： 77.8 GiB 的 Mac 将共存模型对的上限限制在约 55 GiB；体积过大的模型会相互驱逐，并触发长达数分钟的冷启动加载。
• 先测试后部署： 在将优胜模型晋升至 Ollama 用于生产路由之前，务必先在 LM Studio（MLX 运行时）中进行基准测试。
• 嵌入模型变更会导致索引失效： 更换 nomic-embed-text 会强制知识库全量重新索引；切勿将其视为简单的配置调整。
• 同步所有启动脚本： 在调整服务参数时，需对三个启动脚本进行一致更新；并安排在低流量时段进行更换，以避免旧网关服务中断。