LangChain4j模型参数配置实战：从temperature到采样机制，一文搞定

1. 一次事故引发的思考：模型参数真的会改变产品生死

去年年底，我们客服机器人突然“性格大变”。原本回答简洁、语气礼貌的AI，一夜之间变得啰嗦又飘忽：同一个问题，用户上午问和下午问得到的答案竟然能差出好几个意思，甚至偶尔冒出一句带情绪的话。排查了半天，Prompt没动，模型版本没换，知识库的召回也没问题。最后在配置中心里翻到一个不起眼的改动——有人把 temperature 从 0.2 调成了 0.8。

改回去，一切恢复正常。

这不是段子。这是我用 LangChain4j 做生产项目时真实踩过的情况。也正是从那次之后，我开始把“模型参数”当成一等公民来管理，而不是随手在 Builder 链上填一个数字。这篇是 LangChain4j 从入门到精通系列的第 5 篇，专门讲模型参数：它们是什么、怎么配、背后是什么原理、不同模型厂商之间有什么差异，以及我踩过的那些文档里根本不会写的坑。

先说清楚范围。LangChain4j 里的“模型”不止聊天模型，还有嵌入模型、图像模型、语音模型等。但日常项目里 90% 的时间都在跟 ChatModel 和 EmbeddingModel 打交道，所以我这篇文章也重点围绕这两类，尤其是 ChatModel 的参数体系。至于具体怎么安装依赖、怎么拿到 API Key、怎么跑通第一个 Hello World，前面几篇已经讲过了，不重复。

如果你只是想在项目里把“能跑”变成“跑得稳”，或者你已经在用 LangChain4j 但面对那一堆 .temperature()、.topP()、.maxTokens() 不知道该填什么，这篇文章应该能帮你省不少时间。

一句话总结：模型参数不是锦上添花，它是决定 AI 产品是“稳定可用”还是“偶尔抽风”的分水岭。

2. ChatModel 参数全景图：Builder 链上每个字段都不是摆设

LangChain4j 的模型构建统一走 Builder 模式，无论底层接的是 OpenAI、Ollama 还是通义千问，写法都长得很像。下面这段是用 OpenAI 兼容接口构建聊天模型的典型代码：

java复制ChatModel model = OpenAiChatModel.builder()
        .apiKey(System.getenv("OPENAI_API_KEY"))
        .modelName("gpt-4o-mini")
        .temperature(0.7)
        .topP(0.9)
        .maxTokens(2048)
        .stop(List.of("END"))
        .seed(42)
        .timeout(Duration.ofSeconds(60))
        .maxRetries(2)
        .logRequests(true)
        .build();

这些参数看着不起眼，但每一个都在直接干预模型的行为。我把它们分成三组来理解：采样控制组、输出边界组、稳定性与观测组。

2.1 采样控制组：temperature 与 topP

这一组决定模型“胡说八道的程度”。

• temperature：控制生成结果的随机性，值越大，输出越发散；值越小，输出越保守、越倾向于高概率词汇。OpenAI 系模型通常支持 0 到 2，默认是 1.0 或 0.7，看具体厂商。
• topP：核采样参数，只从累计概率超过阈值的 token 集合里采样。比如 topP=0.9 意味着只考虑概率累加达到 90% 的一批候选词，把尾巴上的低概率词砍掉。

OpenAI 官方文档里有个反复强调的建议：不要同时调整 temperature 和 topP，改其中一个就好，两个一起动容易让结果变得难以预期。我实际测下来确实是这样，一般固定 topP=1.0，只动 temperature 就够了。

2.2 输出边界组：maxTokens、stop 与 seed

这一组控制输出“最长能到哪、什么时候停止、能不能复现”。

• maxTokens：限制生成的 token 数量上限，防止模型无限写下去。需要说明的是，这个值只限制“补全”部分，不包含输入 token。
• stop：停止序列。模型在生成过程中一旦遇到列表里的字符串，就会立即停止输出。常用于结构化输出：让模型在生成结束时自动输出一个 END 标记，或者用 \n\n 来防止它啰嗦下去。
• seed：随机种子。部分厂商支持传入固定种子来“尽量”复现同一次生成结果。注意我用的是“尽量”，后面避坑部分会细说。

2.3 稳定性与观测组：timeout、maxRetries 与 logRequests

这一组不直接影响生成内容，但决定了你在生产环境里会不会半夜被拉起来处理告警。

• timeout：单次请求超时时间。模型输出越长，耗时越长，设太短会导致长回答被硬生生掐断。
• maxRetries：请求失败后的自动重试次数。网络抖动、上游 429 限流的时候，这个参数能救命。
• logRequests / logResponses：开启后会在日志里打印完整的请求和响应内容，排查问题非常好用，但生产环境建议只在调试期开启，否则日志量会比较大。

用一个表格把这组参数快速过一遍：