你在 RAGFlow 里加一个 Ollama 模型，卡在 Base URL 那一栏：填本机地址还是容器名，端口带不带，API Key 是空着还是随便写？填错往往不是直接报错，而是列表拉不出来、对话转圈、日志里一行连接失败。这篇按「填什么、怎么验、错了怎么查」三步走，把判断标准交给你，具体端口和地址以你本机部署形态为准。
在 RAGFlow 里加一个 Ollama 模型，很多人卡在 Base URL 那一栏：填本机地址还是容器名，端口带不带，API Key 是空着还是随便写。麻烦的地方在于填错往往不直接报错，而是模型列表拉不出来、对话一直转圈、日志里一行连接失败，看着像 RAGFlow 的问题，其实只是地址写法不对。
这篇按「填什么、怎么验、错了怎么查」三步走，把判断标准交给你。具体端口和地址以你本机部署形态为准，涉及组件配置和版本差异的地方，到 工具目录（/tools） 和 指南中心（/guides） 核对当时的说明。
Base URL 该填成什么形状
第一件事是分清 Ollama 原生接口和 OpenAI 兼容接口是两回事。RAGFlow 加模型时通常要你选类型，选哪个类型决定你该填哪个地址，类型选错，地址再对也连不上。填之前先确认三件事：RAGFlow 跑在宿主机还是容器里、Ollama 跑在同一台还是另一台机器、两者是否在同一个网络命名空间。
- RAGFlow 在容器里、Ollama 在宿主机上：容器内的 127.0.0.1 指的是容器自己，不是宿主机，这里要换成宿主机在容器网络里可达的地址
- RAGFlow 和 Ollama 都在同一台宿主机、都用容器跑：两者能否互访取决于是否同一网络，不在同一网络就得用能被对方解析的名字
- Ollama 在另一台机器：直接换成对端可达的内网 IP 或域名，别再用本机回环地址
- 地址末尾不要自己加路径后缀，先按最朴素的形态填，不通再加，避免两层路径叠加
| 部署形态 | 填地址时要考虑的点 | 常见填错 |
|---|---|---|
| RAGFlow 容器 + Ollama 宿主机 | 宿主机在容器网络中的地址 | 写成 127.0.0.1 |
| 两者都在宿主机容器 | 是否同一网络、能否用服务名互访 | 用过一次就以为通用 |
| Ollama 在另一台机器 | 对端内网 IP 或域名、防火墙放行 | 仍写本机回环 |
| 中间挂了网关 | 网关的对外地址 | 把网关地址和 Ollama 地址混填 |
判断依据就这三条，不用背结论。换一种部署方式，地址写法大概率要跟着变，所以别人能用的地址你直接抄过来不一定有效。
API Key 那栏到底填什么
本地 Ollama 默认不做鉴权，这栏多数情况留空即可，不用编一个。但有些表单会把该字段设成必填，留空提交不过去，那就填一个占位字符串，比如随便一串字母，关键是它不会被真的校验。别把云端厂商的 key 填到这里，它和本地服务没有对应关系，只会把排查方向带偏。
- 直连 Ollama
- 一般没有鉴权环节，API Key 留空或填占位串
- 经网关或中转
- 鉴权由网关侧发放，key 与 Ollama 本身无关，这栏通常是必填
- 必填表单留空
- 填占位字符串即可，不要填真实云端凭证
怎么判断要不要 key？先直连 Ollama 发一次最小请求，能通就说明不需要 key；再经网关发一次，如果返回 401 之类的未授权响应，就说明要补鉴权头。两步一对比，答案就出来了。如果中间那层网关本身还做了转发改写，鉴权规则以网关侧文档为准。
填完之后的连通验证顺序
- 先验网络层在 RAGFlow 所在的那台机器或容器里，对目标地址做一次连通性测试，证明路径通，再谈应用层。
- 再验服务层用一次最小请求确认 Ollama 真的在响应。端口开着但服务没起来很常见，只测端口会误判。
- 最后回界面验在 RAGFlow 里拉一次模型列表或发一次对话，把失败范围缩到最小，看是列表拉不出来还是对话报错。
- 记录每步结果把三步的输出记下来，出问题能一眼看出是网络、服务还是表单配置的问题。
如果这几步里有一环反复失败，先别急着改 RAGFlow 的配置，把对应那一环单独查通再往下走，否则改了半天可能改的是没问题的那一层。
连不上时的排查次序
按「地址形状 → 网络可达 → 服务存活 → 鉴权 → 模型是否已拉取」这个顺序查，不要跳步。拉不到模型列表，多半出在地址或鉴权；能拉到列表但对话报错，多半是模型没下载或名字对不上。这两类现象对应的方向完全不同，先看清现象再动手。
| 现象 | 优先怀疑 | 下一步动作 |
|---|---|---|
| 列表拉不出来 | 地址形状或鉴权 | 回到地址与 key 两节逐条对照 |
| 能拉列表、对话失败 | 模型未拉取或名字不符 | 在 Ollama 侧确认模型存在且名称一致 |
| 偶发超时 | 网络或服务负载 | 测连通性与响应时间，排除网络抖动 |
| 改了配置仍不通 | 服务缓存了旧连接 | 重启对应服务后再验一次 |
- 容器场景优先怀疑网络模式，host 模式和 bridge 模式下的地址写法完全不同，这是反复踩的坑
- 改完配置记得重启对应服务再验，有些组件会缓存上一次的连接状态
- 跨机器联调时顺手确认防火墙是否放行了对应端口
- 把每次改动的值和结果记一行，快速回滚有依据
常见问题
RAGFlow 里对接 Ollama，Base URL 填 127.0.0.1 为什么不通？
因为 RAGFlow 自己跑在容器里，127.0.0.1 指的是它自己那个容器，不是你的宿主机。要么换成宿主机在容器网络里可达的地址，要么让两边共享 host 网络。先确认 RAGFlow 的部署形态，再决定填哪个地址。
本地 Ollama 没有鉴权，API Key 可以随便填吗？
多数情况留空就够。只有当表单强制必填时，才随便填一个占位字符串，它不会被校验。但如果中间加了网关做统一分发，那这栏就是真鉴权，必须用网关发的 key，跟 Ollama 无关。先确认有没有中间层。
模型列表能拉出来，但对话一直失败，怎么回事？
能拉列表说明地址和鉴权都对，问题多半在模型本身：名字写错、模型还没拉下来、或者显存不够加载不起来。去 Ollama 侧确认模型已就绪、名字与 RAGFlow 里填的一致，再重试一次。
