ollama search api key 怎么配

你本地 Ollama 已经能跑模型，但想让它联网搜、或者给 WebUI、知识库、Agent 挂上搜索能力，就卡在「这个 key 到底该配在哪」——配进 Ollama 本体？配进前端？还是配进搜索服务？这篇按来源、落点、验证三步讲清，并给一份配完不生效的排查顺序。

本地 Ollama 已经能跑模型，但你很快会冒出新需求：让它联网搜一下、给 WebUI 加检索、或者拿它当 Agent 的大脑。这时候「搜索 API key」就冒出来了——到底该配在 Ollama 本体、配在前端、还是配在搜索服务里？配错位置的典型症状是：key 明明没打错，日志里就是读不到。

这篇按来源、落点、验证三步走。先确认这把 key 是谁发的，再对号入座写进哪一层，最后给一份配完不生效的排查顺序。只讲判断标准和能动手的动作，具体数字和版本别在这儿找，去站内对应页面核对当时的数值。

先分清这个「搜索 API key」是谁发的

最容易踩的坑，是把「模型平台凭据」当成「搜索服务凭据」往外填。Ollama 本身是本地推理服务，默认不带联网搜索能力，也就不存在官方搜索 key 这回事。你手里那把 key，大概率来自某个搜索或检索服务商，而不是 Ollama。

• 先到 /ai-nav/category/ai-search 看看搜索工具都是谁在提供，心里有个来源清单
• 确认这把 key 是搜索服务发的，还是模型平台发的，两者别混
• 如果框里同时有「模型 key」和「搜索 key」两个输入，说明要分别配两条
• 不确定就翻服务商后台的密钥页面，看它标注的能力范围

key 该写进哪一层：按链路对号入座

一条完整的链路通常是：前端或 Agent → 搜索服务 → 把结果回填给模型 → Ollama 出答案。key 基本落在前端或中间件这一层，而不是 Ollama 进程本身。所以别在 Ollama 的启动参数里找搜索配置，找错了方向。

环境变量

命令行下持久生效的常见方式，注意变量导出写法和是否写进 shell 配置文件，细节对照 /ai-dict/category/infra

配置文件

一些前端或 Agent 框架用独立配置文件存凭据，改完多半要重启或热加载

界面输入框

某些 WebUI 允许在设置页直接填，优先级可能高于环境变量，排查时要考虑到

1. 确定落点按你的链路判断：是给前端配、给知识库配、还是给 Agent 框架配。多个组件都要搜，就分别配，不要指望配一处全都通。
2. 写入命令行场景优先用环境变量，并写进 shell 配置文件让新开的终端也生效；界面场景直接填设置页并保存。
3. 配对知识库或检索类工具常要两条凭据：一条模型侧、一条搜索或重排侧。只配一半，表现就是能连上但搜不出结果。
4. 保护key 属于凭据，写进文件时注意权限，别提交进代码仓库；改之前先备份原配置。

判断标准很简单：哪个组件负责发出搜索请求，key 就配在它读得到的地方。如果某个环节只是转发请求，它多半不需要自己的 key，除非它也要独立调用搜索接口。

配完不生效？按这个顺序排查

配完发现搜不出来，先别急着换 key。大部分问题出在「没读到」和「读到了被拒」这两类，按下面的顺序过一遍，能快速定位在哪一环。

• 先看服务有没有重启或热加载，环境变量改动不重启进程基本不生效
• 单独拿搜索服务做一次直连测试，确认 key 本身有效、额度没用完、区域没被限制
• 再看中间件日志，区分是「压根没读到 key」还是「读到了但被搜索端拒绝」
• 检查有没有被更高优先级的配置覆盖，比如容器里另写了一份环境变量，或界面里也存了一份
• 延迟或超时别急着怪 key，先用 /tools/speed-test 量一次基线，确认是不是链路本身慢

# 直接验证环境变量有没有被当前进程读到
printenv | grep -i SEARCH
# 或在启动脚本里显式导出后再拉起服务
export SEARCH_API_KEY=你的key
# 然后重启对应的前端或中间件进程

如果日志显示读不到变量，多半是导出位置不对，或者服务启动时还没加载到那份配置；如果显示读到了但被拒，就回去查 key 的权限和额度。这两类的修法完全不同，别混着改。

还有一种情况是只对某些场景不生效，比如本地能用、关掉某个开关就断。那通常是链路里某个组件被停用了，而不是 key 的问题。排查时把链路逐步接通，比一次性全开更容易看出断在哪。