openJiuwen Agent Runtime Java 接入真实大模型:LLM 配置与 apiconfig.json 完全指南

原创2026-11-02 09:35:511,989 阅读
文章标签:人工智能AI Agent后端

openJiuwen Agent Runtime Java 接入真实大模型:LLM 配置与 apiconfig.json 完全指南

openJiuwen Agent Runtime Java 是 Agent 分布式运行时的 Java 实现仓库,承载 Agent Server、Runtime Manager 等运行时组件。本文带你用最快的方式让它接入真实大模型:只需一份 apiconfig.json,或几行 openjiuwen.service.llm Spring 配置,主 demo 即可走通 Query → Orchestrator → JiuwenCoreAgentHandler → Runner → LlmAgent 全链路。

1️⃣ 为什么必须先配置 LLM 才能启动

主 demo 固定走真实 Core 链路,启动时会校验大模型配置:

Query API -> ServeOrchestrator -> JiuwenCoreAgentHandler -> Runner -> ReActAgent

三个字段缺一不可:

字段 作用
api-key 模型服务的访问密钥
api-base 模型服务地址(如 https://api.example.com/v1)
model-name 模型名称(如 gpt-4o-mini)

未配置时进程会在启动阶段直接失败,而不是运行时报错——这是有意的 fail-fast 设计,帮你尽早发现配置问题。

2️⃣ 运行时全景:LLM 在架构中的位置

openJiuwen Agent Runtime Java 分布式运行时而接入 LLM 的架构图

如上图所示,Agent Server 内嵌 Agent-Core,LLM 属于运行时依赖的外部服务之一;配置正确后,所有 Query 请求都会经由 Agent Server 出站调用真实大模型。

3️⃣ 最快上手:复制一份 apiconfig.json

仓库自带模板文件 apiconfig_example.json,复制为本地 apiconfig.json(该文件被 git 忽略,不会泄漏密钥)并填写真实值:

{
  "API_BASE": "https://api.example.com/v1",
  "API_KEY": "replace-with-your-api-key",
  "MODEL_PROVIDER": "OpenAI",
  "MODEL_NAME": "replace-with-your-model-name",
  "LLM_SSL_VERIFY": "true"
}
字段 说明 对应 Spring 属性
MODEL_PROVIDER 模型客户端 provider,默认 OpenAI openjiuwen.service.llm.provider
API_KEY API 密钥,支持 ${ENV_VAR} 占位符 api-key
API_BASE 模型服务地址 api-base
MODEL_NAME 模型名称 model-name
LLM_SSL_VERIFY 是否校验 TLS 证书,默认 true ssl-verify

⚠️ 注意两个校验规则:文件必须是 1 MiB 以内的 JSON 对象;显式指定但不可读的文件会直接抛 IllegalStateException,不会静默回退到下一优先级。

4️⃣ 三种方式指定配置文件(优先级从高到低)

ApiConfigLoader(ApiConfigLoader.java)按顺序只选择一个配置文件:

  1. 显式 Spring 属性 openjiuwen.service.llm.config-file:
mvn -pl agent-service-demo -am spring-boot:run \
  -Dspring-boot.run.arguments="--openjiuwen.service.llm.config-file=/path/to/apiconfig.json"
  1. 环境变量 OPENJIUWEN_API_CONFIG:
OPENJIUWEN_API_CONFIG=/path/to/apiconfig.json \
mvn -pl agent-service-demo -am spring-boot:run
  1. 自动发现:auto-discover=true 时,从当前工作目录起最多向上查找 6 层目录中的 apiconfig.json。demo 的基础配置 application-base.yml 已默认开启 auto-discover: true。

💡 常见误区:auto-discover=false 只关闭第 3 种来源,显式路径和环境变量仍然有效。

5️⃣ 用 Spring 属性配置(更适合配置中心/CI 注入)

在 application.yml 或本地覆盖文件中直接写模型参数,demo 提供了被 git 忽略的本地模板 application-base_local.example.yml:

openjiuwen:
  service:
    llm:
      auto-discover: false
      provider: OpenAI
      api-key: your-api-key
      api-base: http://your-host/v1
      model-name: your-model
      ssl-verify: false

复制为 application-base_local.yml 并填入真实值即可,Spring 会自动 import 它覆盖基础配置。

字段合并优先级(LlmConfigResolver 逐字段合并):

非空的 openjiuwen.service.llm.* Spring 配置 > apiconfig.json 字段 > Runtime 默认值

也就是说:文件和 Spring 可以同时存在,字段级互不冲突,Spring 配置优先。

常用参数速查

参数 默认值 说明
provider OpenAI 模型客户端 provider
ssl-verify true 出站 TLS 证书校验
system-prompt "" 系统提示词
temperature 0.6 采样温度
top-p 0.8 核采样阈值
timeout 60s 模型客户端超时
context-window-limit 10 上下文窗口轮数
max-iterations 5 Agent 最大迭代次数

完整规则详见 LlmConfigResolver.java 与官方配置文档。

6️⃣ 进阶:多模型目录与密文密钥

  • 多模型目录:设置 model-selection-enabled=true 后,可在 models 列表中追加 model-id / provider / api-key / api-base / model-name / ssl-verify,主配置作为默认模型(model-id 缺省为 default),启动时会一次性校验全部模型。
  • 密文 API Key:api-key 可保存密文,运行时通过 CredentialDecryptor 的 LLM_API_KEY 场景(如外部 KMS)解密,适合生产环境不落盘明文密钥。
  • 占位符:apiconfig.json 中的 API_KEY 等字段支持 ${OPENAI_API_KEY} 形式的 Spring 占位符,从环境变量注入。

7️⃣ 启动验证:三步确认接入成功

第 1 步:启动 demo(在 service 目录,默认端口 8090)

mvn -pl agent-service-demo -am spring-boot:run

第 2 步:健康检查,确认 agent_loaded: true

curl -s http://localhost:8090/health

第 3 步:发起第一条 Query,能收到大模型生成的回答即接入成功

curl -s http://localhost:8090/v1/query \
  -H 'Content-Type: application/json' \
  -d '{"conversation_id":"demo-c1","message":"hello","stream":false}'

还可以运行仓库自带的冒烟脚本 smoke-query.sh,它会对 /health、非流式/流式 Query、SSE 行为做结构断言(非空 assistant 内容、conversation_id 匹配),专为真实大模型设计:

bash agent-service-demo/example/query/smoke-query.sh

8️⃣ 常见问题排查

现象 原因与解法
启动失败:does not reference a readable regular file config-file 或 OPENJIUWEN_API_CONFIG 指向的路径不存在或不可读,修正路径,不会自动回退
启动失败:LLM API configuration file exceeds 1 MiB 配置文件过大,确认只放了模型配置
启动失败:openjiuwen.service.llm.api-key is required... 三个必填字段在 Spring 与文件中都为空,补齐任一来源即可
密钥含 ${...} 未解析 占位符只能出现在 apiconfig.json 的支持字段中,且需在 Spring 环境能解析到对应变量

总结

  • 最快路径:复制 apiconfig_example.json → 填密钥 → 靠 auto-discover 自动发现 → 启动。
  • 生产推荐:Spring 配置(配置中心/环境变量注入)+ CredentialDecryptor 密文密钥。
  • 记住两个优先级:文件来源是「显式路径 > 环境变量 > 自动发现」,字段值是「Spring 配置 > apiconfig.json > 默认值」。

配置完成后,你就可以阅读 agent-service-demo 文档 继续体验多轮会话、MCP 工具调用等能力,或参考 快速开始指南 部署你自己的 Agent Service 🚀

登录后查看全文
agent-runtime-java