openJiuwen Agent Runtime Java 接入真实大模型:LLM 配置与 apiconfig.json 完全指南
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 在架构中的位置
如上图所示,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)按顺序只选择一个配置文件:
- 显式 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"
- 环境变量
OPENJIUWEN_API_CONFIG:
OPENJIUWEN_API_CONFIG=/path/to/apiconfig.json \
mvn -pl agent-service-demo -am spring-boot:run
- 自动发现:
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 🚀
