LangChain4j集成Ollama时Property配置不生效

Question

在使用 LangChain4j 集成 Ollama 时，常见问题为通过 `application.properties` 或 `yaml` 配置的属性（如 `ollama.base-url`、`ollama.model`）未生效，导致请求默认本地地址或模型名称错误。问题根源常在于配置项命名不正确或缺少对应的配置绑定类，亦或是未启用 ConfigurationProperties 注解扫描。此外，LangChain4j 的 OllamaChatModel 若未通过 Spring Bean 方式注入，将忽略外部配置，直接使用硬编码默认值。需确保依赖 `langchain4j-spring-boot-starter` 并正确配置前缀绑定，否则自定义参数无法传递至底层客户端。

Answer 1

1. 问题背景与常见现象

在使用 LangChain4j 集成 Ollama 构建本地大模型应用时，开发者普遍遇到的一个痛点是：通过 application.properties 或 application.yml 配置的属性如 ollama.base-url 和 ollama.model 未生效。系统仍尝试连接默认地址（如 http://localhost:11434）或加载默认模型名称，导致请求失败或模型调用异常。

这种现象常出现在 Spring Boot 应用中，尤其是在快速原型开发阶段，开发者误以为引入依赖即可自动绑定配置，而忽略了 LangChain4j 对配置注入机制的严格要求。

2. 核心原因分析

• 配置项命名不规范：LangChain4j 要求配置前缀为 langchain4j.ollama，而非简单的 ollama。
• 缺少 ConfigurationProperties 扫描：Spring Boot 默认不会扫描第三方库的配置类，需显式启用。
• 未使用 Starter 依赖：若仅引入 langchain4j-ollama 而非 langchain4j-spring-boot-starter，则自动配置功能不可用。
• Bean 注入方式错误：手动 new OllamaChatModel() 将绕过 Spring 容器，导致配置无法注入。

3. 正确配置方式详解

要使外部配置生效，必须遵循以下结构：

配置项	正确格式	错误示例
Base URL	langchain4j.ollama.base-url=http://ai-server:11434	ollama.base-url=...
模型名称	langchain4j.ollama.model=llama3:8b	model=llama3
超时设置	langchain4j.ollama.timeout=60s	timeout=60

4. 必要依赖与自动配置支持

确保 Maven 中包含如下关键依赖：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-spring-boot-starter</artifactId>
    <version>0.30.0</version>
</dependency>

该 Starter 包含了 @ConfigurationProperties 绑定类和自动配置类 OllamaAutoConfiguration，能将配置映射到 OllamaChatLanguageModel 实例中。

5. 启用 ConfigurationProperties 扫描

在主启动类或配置类上添加注解以启用属性绑定：

@SpringBootApplication
@EnableConfigurationProperties
public class AiApplication {
    public static void main(String[] args) {
        SpringApplication.run(AiApplication.class, args);
    }
}

此注解确保 Spring 能识别并绑定 langchain4j.ollama.* 到对应的 POJO 配置类。

6. Bean 注入最佳实践

应始终通过依赖注入获取 OllamaChatModel，避免硬编码：

@Service
public class ChatService {

    private final OllamaChatLanguageModel chatModel;

    public ChatService(OllamaChatLanguageModel chatModel) {
        this.chatModel = chatModel;
    }

    public String ask(String prompt) {
        return chatModel.generate(prompt);
    }
}

这样可确保使用的实例是由 Spring 容器根据配置创建的。

7. 验证配置是否生效

可通过以下方式验证配置是否正确加载：

@Component
public class ConfigValidator implements CommandLineRunner {

    @Value("${langchain4j.ollama.base-url}")
    private String baseUrl;

    @Override
    public void run(String... args) {
        System.out.println("Ollama Base URL: " + baseUrl);
    }
}

启动时观察输出，确认值来自配置文件而非默认值。

8. 流程图：配置加载全过程

graph TD
            A[application.yml/properties] --> B{是否有 langchain4j-spring-boot-starter?}
            B -- 是 --> C[Spring Boot 自动配置]
            B -- 否 --> D[仅使用默认参数]
            C --> E[@ConfigurationProperties 绑定]
            E --> F[创建 OllamaClient 实例]
            F --> G[注入 OllamaChatLanguageModel Bean]
            G --> H[服务类通过 DI 使用模型]
            H --> I[发起请求至指定 base-url 和 model]

9. 常见误区与排查清单

1. 检查是否遗漏 langchain4j-spring-boot-starter 依赖
2. 确认配置前缀为 langchain4j.ollama.* 而非 ollama.*
3. 查看日志中是否出现 Binding to target [Bindable@...] 成功信息
4. 调试时打印 chatModel.toString() 查看实际参数
5. 确保没有多个 OllamaChatModel Bean 导致冲突
6. 检查网络连通性及 Ollama 服务是否运行于目标地址
7. 确认模型已在 Ollama 中通过 ollama pull llama3 下载
8. 避免在测试中使用 new OllamaChatModel(...)
9. 启用 debug 日志：logging.level.dev.langchain4j=DEBUG
10. 验证 Spring Context 是否加载了预期的 Bean

10. 扩展思考：企业级集成建议

在生产环境中，建议结合 spring-cloud-config 或 Consul 实现动态配置管理。同时可封装 OllamaChatLanguageModel 提供统一的 AI 调用网关，加入熔断、限流、审计日志等能力。对于多模型场景，可通过 @Qualifier 注解区分不同命名的 Bean。

此外，考虑使用 RetryTemplate 处理临时网络抖动，并利用 Micrometer 监控请求延迟与成功率。