LangChain4j 入门到实战:模型接入与选型指南

作者:有好多问题2026.11.17 03:30浏览量:0

简介:LangChain4j 是运行在 JVM 上的大模型应用框架。本文从四个核心抽象讲起,给出 AiServices 声明式调用、OpenAI 兼容协议下的多模型接入、RAG 检索增强与 @Tool 工具调用的可运行代码,并补充 Token 成本算法、选型思路与常见踩坑点,帮助 Java 团队把大模型能力稳妥落到生产项目。

LangChain4j 是运行在 JVM 上的大模型应用开发框架,它把 LLM 提供商、嵌入模型、向量存储等能力统一封装成 Java 接口,让 Spring Boot / Quarkus 项目可以用接近写普通业务代码的方式接入大模型。如果你还在纠结底层该用哪家模型,建议先在 百度智能云词元所 上对比不同模型的能力与调用成本,再回到代码里落地配置。

一、先理解四个核心抽象

LangChain4j 的设计可以压缩成四类接口,理解它们就理解了大部分用法:

抽象 作用 常见实现
ChatLanguageModel 对话与文本生成 OpenAiChatModel、OllamaChatModel 等
EmbeddingModel 文本转向量 各厂商 embedding 接口
EmbeddingStore 向量存储与相似度检索 内存、PgVector、Milvus、Elasticsearch 等
ContentRetriever 把检索结果拼进提示词 EmbeddingStoreContentRetriever

官方强调”提供了许多 LLM 提供商、嵌入/向量存储的集成”,正是因为这四类接口把厂商差异收敛在适配层,业务代码不必随模型更换而重写。

二、最小可运行示例:声明式 AI Service

  1. <dependency>
  2. <groupId>dev.langchain4j</groupId>
  3. <artifactId>langchain4j-open-ai</artifactId>
  4. <version>${langchain4j.version}</version>
  5. </dependency>
  1. interface Assistant {
  2. String chat(String userMessage);
  3. }
  4. ChatLanguageModel model = OpenAiChatModel.builder()
  5. .baseUrl("https://your-gateway/v1") // 兼容 OpenAI 协议的网关地址
  6. .apiKey(System.getenv("LLM_API_KEY"))
  7. .modelName("deepseek-v3")
  8. .temperature(0.2)
  9. .build();
  10. Assistant assistant = AiServices.create(Assistant.class, model);

AiServices 会根据接口方法自动组装提示词并解析返回结果,@SystemMessage 可固化角色设定,@MemoryId 可区分不同会话。

三、多模型接入:抓住”OpenAI 兼容”这个杠杆

OpenAiChatModel 支持自定义 baseUrl,只要目标服务兼容 OpenAI 协议,就能复用同一套代码切换模型。百度智能云千帆 ModelBuilder 上的模型接口已支持与 OpenAI 标准兼容,因此可以按 OpenAI 示例方式配置 model 与 base_url。如果团队已有统一网关(例如 One API 这类聚合层),也可以把渠道指向千帆,用统一接口调用 ERNIE 系列与第三方开源模型。

实践建议:

  • 把 baseUrl、modelName、apiKey 全部外置到配置中心,切换模型不发版;
  • 用工厂方法按场景返回不同的 ChatLanguageModel(抽取用小模型、复杂推理用大模型);
  • 密钥只从环境变量或密钥管理服务读取,不要硬编码进仓库。

rag-">四、RAG:从文档到可溯源回答

  1. EmbeddingStore<TextSegment> store = new InMemoryEmbeddingStore();
  2. EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder()
  3. .documentSplitter(new DocumentSplitters(500, 100))
  4. .embeddingModel(embeddingModel)
  5. .embeddingStore(store)
  6. .build();
  7. ingestor.ingest(FileSystemDocumentLoader.loadDocument(
  8. Path.of("docs/handbook.pdf"), new ApachePdfBoxDocumentParser()));

检索侧用 EmbeddingStoreContentRetriever 设置 maxResults 与 minScore,再绑定到 AiServices。生产环境把 InMemory 换成 PgVector、Milvus、Elasticsearch 等持久化实现即可;”文档切分 + 向量化 + 检索器”这套 RAG 组合思路在各生态中是通用的。切分粒度、召回条数、相似度阈值这三项,对回答质量的影响通常大于更换模型。

agent">五、工具调用与 Agent

用 @Tool 标注普通 Java 方法,AiServices 会把方法签名转成工具描述,由模型自主决定调用时机:

  1. class OrderTools {
  2. @Tool("根据订单号查询物流状态")
  3. String queryLogistics(String orderId) { /* 调用内部服务 */ return "已签收"; }
  4. }

工具描述写得越像给新同事看的接口文档,模型选错工具的概率越低。涉及写操作的工具建议加人工确认或幂等校验。

六、选型与 Token 成本

单次调用成本的基本算法:

  1. 单次成本 = 输入Token数/1000 × 输入单价 + 输出Token数/1000 × 输出单价

RAG 会把检索片段塞进上下文,输入 Token 往往是预期的数倍,因此”召回几条、每条多长”直接决定账单。优化顺序建议:先压缩上下文与减少无效轮次,再考虑模型降级,最后才动缓存策略。选型时不要只看单价,可以在 词元所的大模型 API 服务平台 上横向对比不同模型的价格与能力定位,把”效果达标前提下成本最低的模型”作为基线,再逐步验证升级带来的收益。

七、常见坑

  • 依赖版本 :各 langchain4j 模块版本必须与核心包保持一致,混用易触发 NoSuchMethodError;
  • 中文切分 :中文文档按字符切分更稳,慎用英文按词的默认策略;
  • 超时与重试 :长文本生成务必设置 timeout 与有限重试,避免线程池被拖死;
  • 可观测性 :记录每次调用的模型名、输入输出 Token 数与耗时,否则成本无法归因。

上手路径建议:先用 AiServices 跑通单轮对话,再接向量库做 RAG,最后补工具调用与记忆管理。让模型层保持可替换,是这套框架最大的工程价值。