maxkb ollama api key

在 MaxKB 里添加 Ollama 模型时，界面会让你填 API Key 和 API 地址，很多人卡在这一步：Ollama 本地跑着，却不知道 Key 从哪来。这篇把「该填什么、什么情况留空、留空后还不通怎么查」按顺序讲一遍，并给出可照做的排查清单。

在 MaxKB 里加 Ollama 模型的时候，表单上会同时让你填 API 地址和 API Key。地址大多数人都能猜出来写什么，但那串 Key 就卡住了一批人：Ollama 明明在本地跑着，Key 到底去哪申请？答案有点反直觉——多数情况下它压根不需要你去申请，这一栏存在只是为了让 MaxKB 用一套统一格式对接各家模型供应商。

下面按「这栏到底是什么、什么情况填什么、连不上按什么顺序查、怎么确认通了」讲一遍。整个过程不需要你懂 Ollama 源码，照着排查顺序走就行。

先搞明白：Ollama 那栏 API Key 到底是什么

Ollama 默认监听在你本机的一个端口上，服务本身不带鉴权机制，所以它不像那些云端大模型平台，会给你一个官方签发的、可以复制粘贴的 Key。MaxKB 表单里放这一栏，是为了把本地推理服务和云端服务统一成同一种接入方式，不是暗示你必须去某处领一串字符。

• Ollama 本体不自带账号体系，也就没有「官方 Key」这个概念，别满世界找申请入口
• 真正决定能不能连上的是地址、端口、服务有没有起来，而不是这串字符
• 如果你在前面挂了反向代理或网关，并给这个网关配了鉴权，那才有真实 Key 要填，这时以代理方给你的为准
• 判断标准很简单：你的 Ollama 是不是直接暴露给 MaxKB 访问的，是就基本不用管 Key

要不要填：三种场景分别怎么处理

不同部署方式下，Key 和地址的处理完全不一样。下面这张表可以当对照用，先对号入座再动手。

一个常见坑：MaxKB 跑在容器里，Ollama 跑在宿主机上，地址写了 localhost。容器里的 localhost 指容器自己，当然连不上。这不是 Key 的问题，改地址就行。同理，不确定自己属于哪种场景时，先用最简单的本机直连测通，再逐步加反向代理这类复杂度，每加一层都重测一次。

连不上时的排查顺序（照这个顺序走，别乱试）

连接失败时最容易犯的错是同时改地址、改端口、改 Key，改完还是不通，也不知道是哪一项引起的。下面这个顺序一次只验证一件事。

1. 确认服务在跑在跑 Ollama 的那台机器上，用命令行正常对话或列出模型，能出结果说明服务本身没问题。
2. 确认监听可被外部访问默认只监听本机回环地址的话，MaxKB 在别的机器或容器里就够不着。改成对外可达的绑定后，再让 MaxKB 访问，这一步和 Key 无关。
3. 确认模型已拉下来在 MaxKB 里选模型时看列表里有没有目标模型，没有就先拉取，列表空着多半是服务地址还没通。
4. 回头核对表单写法地址末尾斜杠、协议是 http 还是 https、端口是不是写全，这几处逐字对照一遍。

这四步的意义在于把变量拆开。每步只改一个东西，改完立刻重试，不通就退回去，这样出错时你就能定位到具体是哪一层的问题，而不是在一堆猜测里打转。

填完怎么验证，以及什么时候这套做法不适用

验证不用搞复杂：在 MaxKB 里建一个最简单的应用，发一句普通的话，能正常返回结果就说明链路通了。如果返回报错，先别急着改 Key，把地址和模型名再对一遍。

• 想看清请求格式，可以先在命令行直接打一次接口，看返回体长什么样，再回去对照表单每个字段
• 列表里能看到模型、简单提问能出结果，这两点同时满足才算真通了
• 不适用的情况一：走的是云厂商托管服务，那些平台确实要正经申请 Key，不能留空
• 不适用的情况二：多人共用一台推理机且做了访问控制，Key 和地址都得按运维统一给的来
• 不适用的情况三：你的 Ollama 被包在某套企业内部网关后面，规则以网关文档为准

顺带说一句，如果你不只是在本地跑 Ollama，还打算同时接几个不同的模型供应商，那统一管理 Key 和地址会变成一件麻烦事。各家价格和接入方式差异不小，具体数字别凭印象记，到站内价格追踪页面核对当时的数字再决定怎么配。