LangChain4j Ollama 模型名写错抛 NullPointerException

Ollama 模型名写错，LangChain4j 却抛 NullPointerException，栈里连模型名都不提。真正的原因藏在 HTTP 层：/api/chat 对不存在的模型返回 404，响应体为空。retrofit 拿到的 Response.body() 是 null，OllamaClient 回调直接对它调 byteStream()，NPE 就这么冒出来。看到这类 NPE 加 retrofit/OkHttp 栈，先去看服务端到底返回了什么。

Issue & Env（案发现场与环境）

业务场景：本地用 Ollama 跑模型，Java 侧用 LangChain4j 的 OllamaChatModel 调生成。
触发前提：OllamaChatModel.builder().modelName("...") 里写的模型名，本地压根没 ollama pull 过。
环境：langchain4j-ollama 1.0.0-alpha1（栈里可见），Ollama 本地服务，retrofit 2.9.0 + OkHttp 4.12.0。
现象：调用当场抛 NPE，报错信息里没有任何「模型不存在」的提示。

StackTrace（堆栈日志）

报错原文来自 issue #2365：

java.lang.NullPointerException: Cannot invoke "okhttp3.ResponseBody.byteStream()" because the return value of "retrofit2.Response.body()" is null
        at dev.langchain4j.model.ollama.OllamaClient$2.onResponse(OllamaClient.java:164) ~[langchain4j-ollama-1.0.0-alpha1.jar:na]
        at retrofit2.OkHttpCall$1.onResponse(OkHttpCall.java:161) ~[retrofit-2.9.0.jar:na]
        at okhttp3.internal.connection.RealCall$AsyncCall.run(RealCall.kt:519) ~[okhttp-4.12.0.jar:na]
        at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1136) ~[na:na]

栈里全是 HTTP 客户端。Response.body() 返回 null 是核心线索。这个信号通常意味着响应不是 2xx，错误体被 retrofit 放进了 errorBody()。

Reproduce（复现代码）

写一个本地不存在的模型名：

OllamaChatModel model = OllamaChatModel.builder()
        .baseUrl("http://localhost:11434")
        .modelName("qwen2.5:7b-not-pulled")
        .build();

String answer = model.chat("你好");

只要本地没 ollama pull qwen2.5:7b-not-pulled，这行就抛上面的 NPE。

Root Cause（根因分析）

NPE 只是二次伤害

Ollama 的 /api/chat 收到不存在的模型名时，返回 HTTP 404，且响应体为空，或结构不符合 LangChain4j 的预期。retrofit 遇到非 2xx，Response.body() 就是 null。LangChain4j 的 OllamaClient 回调没做判空，直接对 body 调 byteStream()，于是抛 NPE。

为什么难查

报错里既没有模型名，也没有 404。你看到的只是 HTTP 客户端的 NPE。模型名写错和 NPE 之间，隔了一层没被处理的错误响应。这是整件事最绕的地方。

关键点

真实原因在 HTTP 状态码里。看到「NPE + retrofit/OkHttp 栈」，第一反应该是去看服务端返回了什么状态码和 body。

后续版本

issue #2365 期望的修复，是把 NPE 换成清晰的 IllegalConfigurationException，对应 PR #2369。这一修复落在哪个版本区间，社区说法，截至撰写时未核实。

The Fix（解决方案）

1. 先用命令行确认模型存在

ollama list
ollama pull qwen2.5:7b

模型名必须和 ollama list 里的逐字一致，注意 tag，比如 :latest、:7b。

2. 代码里对齐模型名，显式写 baseUrl

OllamaChatModel model = OllamaChatModel.builder()
        .baseUrl("http://localhost:11434")
        .modelName("qwen2.5:7b")
        .build();

把 baseUrl 显式写死，避免连到别的实例。

3. 加防御：先探测 /api/tags

调模型前先确认目标模型在列表里。不在就直接抛自己的业务异常，别让 NPE 冒到业务层。

4. 升级 LangChain4j

升到把该 NPE 改成 IllegalConfigurationException 的版本，报错就能自解释。具体版本号未核实。

小结

Ollama 相关问题先 curl http://localhost:11434/api/tags 和 ollama list，再看 Java 栈。看到 retrofit/OkHttp 里的 NPE，一律先怀疑 HTTP 层返回了非预期响应。