🏪 模型配置
# 更换模型平台
本页介绍 HarnessAgentComponent 使用的生成式模型。需要让 AI 从候选 ID 中选择流程分支时，使用独立的 Jev 智能选择组件，其配置入口是 liteflow.agent.jev.*。
修改组件的 model()，引入对应模块，再配置凭证即可。下表的配置前缀均需加 liteflow.agent.；模块版本与 LiteFlow 一致。
| 平台 | model() 返回值 | 模块 | 凭证前缀 |
|---|---|---|---|
| DeepSeek | DeepSeek.of("deepseek-flash") | liteflow-agent-openai | openai-compatible.deepseek |
| OpenAI | OpenAI.of(modelName) | liteflow-agent-openai | openai |
| Kimi | Kimi.of(modelName) | liteflow-agent-openai | openai-compatible.kimi |
| GLM | GLM.of(modelName) | liteflow-agent-openai | openai-compatible.glm |
| MiniMax | Minimax.of(modelName) | liteflow-agent-openai | openai-compatible.minimax |
| Anthropic | Anthropic.of(modelName) | liteflow-agent-anthropic | anthropic |
| Gemini | Gemini.of(modelName) | liteflow-agent-gemini | gemini |
| DashScope | DashScope.of(modelName) | liteflow-agent-dashscope | dashscope |
例如使用 Gemini 时，配置 liteflow.agent.gemini.api-key。modelName 填该服务实际提供的模型 ID。入口类在 com.yomahub.liteflow.agent.openai、.anthropic、.gemini、.dashscope 包中。
每个平台都可配置 api-key、base-url。内置平台的地址可以不填；代码中的 .apiKey(...)、.baseUrl(...) 优先于配置文件。通常把凭证放在配置中，组件只选择模型即可。
# 接入自建模型服务
OpenAI 兼容服务使用一个自定义名称，例如 gateway：
liteflow.agent.openai-compatible.gateway.api-key=${MODEL_API_KEY}
liteflow.agent.openai-compatible.gateway.base-url=${MODEL_BASE_URL}
@Override
protected ModelSpec<?> model() {
return OpenAICompatible.custom("gateway", "your-deployment-name")
.stream(true);
}
代码中的 gateway 与配置名称一致，API Key 和基础地址都需提供。Anthropic 兼容服务使用 AnthropicCompatible.custom(...)，配置前缀改为 anthropic-compatible.gateway。
模型参数通常使用默认值。需要限制输出长度时，可在 Spec 上设置 .maxTokens(...)；自建模型应通过 .contextWindow(...) 提供真实的上下文 Token 上限，帮助框架正确压缩长对话。具体参数需模型服务支持。
# 模型参数
通常只需在 model() 中选择模型并开启流式。采样参数先沿用服务默认值，额外参数应以目标模型支持范围为准。
| 方法 | 用途 |
|---|---|
stream(boolean) | 请求模型流式响应，配合事件监听使用 |
maxTokens(int)／maxCompletionTokens(int) | 输出 Token 预算，按模型支持情况选择 |
contextWindow(int) | 真实上下文容量，必须为正 |
temperature(double)、topP(double)、topK(int)、seed(long) | 采样设置，一般沿用默认值 |
additionalHeader(...)、additionalBodyParam(...)、additionalQueryParam(...) | 平台额外请求参数 |
generateOptions(...) | AgentScope 原生生成参数；同名生成参数优先于普通链式设置 |
executionConfig(...) | 模型请求超时与重试 |
模型容量目录用于自动识别上下文上限，默认缓存到 ~/.liteflow/model-catalog。可通过 JVM 参数 -Dliteflow.agent.model-catalog.cache-dir=/srv/liteflow/model-catalog 改目录，该参数不通过 Spring Boot 属性绑定。离线环境或自建模型建议显式设置 contextWindow(...)。
需要返回 Java 对象时，见结构化输出。
# Jev 决策模型
Jev 是 TypeSafe 提供的结构化决策模型。liteflow-agent-jev 使用它的 Choice 能力，把客户意图等语义判断转换成 LiteFlow 的选择分支。
liteflow:
agent:
jev:
provider: typesafe
api-key: ${JEV_API_KEY}
timeout: 3s
min-confidence: 0.6
provider 默认为 typesafe，也支持 openrouter 和 laya。切换为 openrouter 后，api-key 填 OpenRouter 的凭据；省略 base-url 和 model 时，默认使用 https://openrouter.ai/api/alpha 与 typesafe/jev-1.13，请求 /decisions。切换为 laya 后指向本地自托管的 laya-serve（pip install "laya[serve]" 后运行，默认 http://127.0.0.1:8000），模型在本地运行，api-key 可留空，默认 model 为 auto，由其路由器按语言选择 checkpoint。显式填写的地址和模型不会随 provider 切换而重置，完整对照见 Jev 依赖与配置。
Jev 组件继承 JevSwitchComponent，必须实现 state()、instructions() 和 choices()。本次用户问题及相关业务上下文由 state() 提供，判断任务与规则由 instructions() 定义，可选分支及其适用边界由 choices() 声明。方法区别与完整示例见编写 Jev 选择组件。
它不使用本页的 model()／ModelSpec 接口，也不配置到 openai-compatible 中。参数说明见 Jev 依赖与配置，可运行页面见客服演示与测试。