模型支持与配置参考

本文档说明了：

智能体服务支持的模型提供商（LLM / 文本嵌入模型 / 网络搜索）。
如何通过 tools_config.json 和 智能体服务请求（REST 和 gRPC）配置模型。
每个提供商所需的 环境变量。
如何向服务传递额外的模型/引擎参数。

1) 配置层级（优先级）

智能体服务按以下顺序解析模型配置：

单次请求级别的覆盖配置（REST 的 stage_model_config，gRPC 的 runningConfig.stageModelConfig）——最高优先级。
仓库工具配置：gui_agents/tools/tools_config.json（通过 load_config() 加载）。
提供商环境变量（API 密钥、Endpint等），加载顺序为：
- 若存在，加载 gui_agents/.env
- 否则，若存在，加载 <repo_root>/.env
- 否则，加载进程环境变量

提示：如果您需要英文的基础配置，可以将 gui_agents/tools/tools_config_en.json 复制为 gui_agents/tools/tools_config.json。

2) 支持的提供商

服务通过 gui_agents/core/mllm.py 路由所有工具调用（用于 LLM / 文本嵌入模型 / 网络搜索），并根据工具配置字段从 gui_agents/core/engine.py 中选择具体的引擎实现：

provider（即 engine_type）
model_name / model

2.1 LLM 提供商（对话 / 多模态）

支持的 provider 值（LLM）：

openai
anthropic
gemini
openrouter
dashscope（通过 DashScope 兼容端点支持 Qwen）
doubao（火山引擎 Ark）
deepseek
zhipu
groq
siliconflow
monica
azure（Azure OpenAI）
vllm（本地 OpenAI 兼容端点）
huggingface（TGI / OpenAI 兼容端点）
aws_bedrock（AWS Bedrock）

2.2 文本嵌入模型（Embedding）提供商

支持的 provider 值（文本嵌入模型）：

openai
gemini
azure
dashscope
doubao
jina

2.3 网络搜索提供商

支持的 provider 值（网络搜索）：

exa
bocha

3) 所需环境变量

以下是 gui_agents/core/engine.py 中引擎使用的环境变量汇总。

3.1 LLM

提供商 (`provider`)	所需环境变量	备注
`openai`	`OPENAI_API_KEY`	可通过工具配置 `base_url` 或请求 `apiEndpoint` 指定自定义基础 URL。
`anthropic`	`ANTHROPIC_API_KEY`	使用 Anthropic SDK（不支持 OpenAI 兼容的 base_url）。
`gemini`	`GEMINI_API_KEY`, `GEMINI_ENDPOINT_URL`	使用 OpenAI 兼容的端点 URL。
`openrouter`	`OPENROUTER_API_KEY`, `OPEN_ROUTER_ENDPOINT_URL`	OpenAI 兼容端点。
`dashscope`	`DASHSCOPE_API_KEY`	默认基础 URL：`https://dashscope.aliyuncs.com/compatible-mode/v1`。
`doubao`	`ARK_API_KEY`	默认基础 URL：`https://ark.cn-beijing.volces.com/api/v3`。
`deepseek`	`DEEPSEEK_API_KEY`	默认基础 URL：`https://api.deepseek.com`。
`zhipu`	`ZHIPU_API_KEY`	使用 ZhipuAI SDK。
`groq`	`GROQ_API_KEY`	使用 Groq SDK。
`siliconflow`	`SILICONFLOW_API_KEY`	默认基础 URL：`https://api.siliconflow.cn/v1`。
`monica`	`MONICA_API_KEY`	默认基础 URL：`https://openapi.monica.im/v1`。
`azure`	`AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`, `OPENAI_API_VERSION`	Azure 端点/版本是必需的；参见第 5 节。
`vllm`	`vLLM_ENDPOINT_URL`	OpenAI 兼容的本地端点 URL（注意环境变量名中的小写 `v`）。
`huggingface`	`HF_TOKEN`	工具配置中还需要指定每个工具的 `base_url`（TGI 端点）。
`aws_bedrock`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`（可选 `AWS_DEFAULT_REGION`）	如果未设置，默认区域为 `us-west-2`。

3.2 嵌入(Embedding)

提供商 (`provider`)	所需环境变量
`openai`	`OPENAI_API_KEY`
`gemini`	`GEMINI_API_KEY`
`azure`	`AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`, `OPENAI_API_VERSION`
`dashscope`	`DASHSCOPE_API_KEY`
`doubao`	`ARK_API_KEY`
`jina`	`JINA_API_KEY`

3.3 网络搜索(Web Search)

提供商 (`provider`)	所需环境变量
`exa`	`EXA_API_KEY`
`bocha`	`BOCHA_API_KEY`

3.4 Lybic 后端（沙盒）

服务默认在 Lybic 沙盒中运行 UI Agent。

LYBIC_API_KEY
LYBIC_ORG_ID
可选：LYBIC_API_ENDPOINT（REST 服务器默认值为 https://api.lybic.cn/）

4) 在服务请求中配置模型

4.1 REST: `stage_model_config`（FastAPI）

REST 请求接受一个 stage_model_config 对象（参见 gui_agents/restful_app.py）：

web_search_engine：字符串（"exa" 或 "bocha"）
对于每个阶段/工具：一个 LLMConfig 对象：
- model_name
- provider（可选）
- api_key（可选）
- api_endpoint（可选）

API 密钥可以通过以下两种方式提供：

环境变量（推荐，适合单租户部署）
请求参数（stage_model_config.*.api_key）——若提供，服务会将其注入工具配置为 api_key，并优先于环境变量。

REST 中的阶段字段与 tools_config.json 中的工具名映射如下：

context_fusion_model → context_fusion
subtask_planner_model → subtask_planner
traj_reflector_model → traj_reflector
memory_retrival_model → memory_retrival
grounding_model → grounding
task_evaluator_model → evaluator
action_generator_model → action_generator
action_generator_with_takeover_model → action_generator_with_takeover
fast_action_generator_model → fast_action_generator
fast_action_generator_with_takeover_model → fast_action_generator_with_takeover
dag_translator_model → dag_translator
embedding_model → embedding
query_formulator_model → query_formulator
narrative_summarization_model → narrative_summarization
text_span_model → text_span
episode_summarization_model → episode_summarization

此外，如果提供了 action_generator_model，服务会将其用作除 websearch、embedding、grounding 之外所有基于 LLM 的工具的通用默认值。

4.2 gRPC: `runningConfig.stageModelConfig`（proto）

gRPC proto 定义：

RunAgentInstructionRequest.runningConfig.stageModelConfig（StageModelConfig）
StageModelConfig.webSearchEngine（字符串："exa" 或 "bocha"）
阶段模型字段（LLMConfig）：
- modelName
- provider（可选）
- apiKey（可选）
- apiEndpoint（可选）

映射关系与 REST 相同（与 tools_config.json 中的工具名称相同）。

API 密钥可以通过以下两种方式提供：

环境变量
请求参数（runningConfig.stageModelConfig.*.apiKey）——若提供，服务会将其注入工具配置为 api_key，并优先于环境变量。

注意：对于 gRPC，proto 中的 provider 是 可选 的。如果省略，服务器将保留工具在 tools_config.json 中的已有提供商。

5) 传递额外的模型/引擎参数

服务请求模式（REST / proto）仅暴露以下每模型覆盖字段：

模型名
提供商
API 密钥
API 端点

对于其他参数（Azure API 版本、Qwen 思考模式开关、速率限制等），应在 gui_agents/tools/tools_config.json 中配置它们在每个工具条目内。

工具条目下的所有额外Key/Value字段,都会作为初始化关键参数传递给底层引擎（参见 gui_agents/tools/tools.py）。常见示例：

api_version（提供商 azure 所需）
azure_endpoint（提供商 azure 所需）
rate_limit
enable_thinking（Qwen）
thinking（Anthropic）

6) 示例

6.1 REST 示例：配置 Gemini（LLM）+ Doubao grounding + Gemini embedding

POST /run_agent（或 POST /submit_task）请求体示例：

{
  "instruction": "打开计算器，计算 123*456",
  "platform": "Windows",
  "mode": "fast",
  "max_steps": 50,
  "authentication": {
    "org_id": "${LYBIC_ORG_ID}",
    "api_key": "${LYBIC_API_KEY}",
    "api_endpoint": "https://api.lybic.cn/"
  },
  "stage_model_config": {
    "web_search_engine": "exa",
    "action_generator_model": {
      "provider": "gemini",
      "model_name": "gemini-2.5-pro"
    },
    "grounding_model": {
      "provider": "doubao",
      "model_name": "doubao-1-5-ui-tars-250428"
    },
    "embedding_model": {
      "provider": "gemini",
      "model_name": "text-embedding-004"
    }
  }
}

此示例所需的环境变量：

LYBIC_API_KEY，LYBIC_ORG_ID
GEMINI_API_KEY，GEMINI_ENDPOINT_URL
ARK_API_KEY（用于 Doubao grounding）
EXA_API_KEY（用于 Exa 网络搜索）

6.1a REST 示例：通过请求参数传递 LLM API 密钥

如果您不想依赖服务器端环境变量（例如，多租户使用），可以在请求中传递提供商密钥：

{
  "instruction": "打开计算器，计算 123*456",
  "platform": "Windows",
  "mode": "fast",
  "max_steps": 50,
  "authentication": {
    "org_id": "${LYBIC_ORG_ID}",
    "api_key": "${LYBIC_API_KEY}",
    "api_endpoint": "https://api.lybic.cn/"
  },
  "stage_model_config": {
    "action_generator_model": {
      "provider": "gemini",
      "model_name": "gemini-2.5-pro",
      "api_key": "<YOUR_GEMINI_API_KEY>",
      "api_endpoint": "<YOUR_GEMINI_ENDPOINT_URL>"
    },
    "grounding_model": {
      "provider": "doubao",
      "model_name": "doubao-1-5-ui-tars-250428",
      "api_key": "<YOUR_ARK_API_KEY>"
    }
  }
}

在这种情况下，您不需要在服务器环境中设置 GEMINI_API_KEY / ARK_API_KEY。

6.2 gRPC 示例：`RunAgentInstructionRequest` 的 JSON 形式

{
  "instruction": "打开计算器，计算 123*456",
  "destroySandbox": false,
  "runningConfig": {
    "backend": "lybic",
    "mode": "FAST",
    "steps": 50,
    "authorizationInfo": {
      "orgID": "${LYBIC_ORG_ID}",
      "apiKey": "${LYBIC_API_KEY}",
      "apiEndpoint": "https://api.lybic.cn/"
    },
    "stageModelConfig": {
      "webSearchEngine": "exa",
      "actionGeneratorModel": {
        "provider": "gemini",
        "modelName": "gemini-2.5-pro"
      },
      "groundingModel": {
        "provider": "doubao",
        "modelName": "doubao-1-5-ui-tars-250428"
      },
      "embeddingModel": {
        "provider": "gemini",
        "modelName": "text-embedding-004"
      }
    }
  }
}

6.2a gRPC 示例：通过请求参数传递 LLM API 密钥

{
  "instruction": "打开计算器，计算 123*456",
  "runningConfig": {
    "backend": "lybic",
    "mode": "FAST",
    "steps": 50,
    "authorizationInfo": {
      "orgID": "${LYBIC_ORG_ID}",
      "apiKey": "${LYBIC_API_KEY}",
      "apiEndpoint": "https://api.lybic.cn/"
    },
    "stageModelConfig": {
      "actionGeneratorModel": {
        "provider": "gemini",
        "modelName": "gemini-2.5-pro",
        "apiKey": "<YOUR_GEMINI_API_KEY>",
        "apiEndpoint": "<YOUR_GEMINI_ENDPOINT_URL>"
      },
      "groundingModel": {
        "provider": "doubao",
        "modelName": "doubao-1-5-ui-tars-250428",
        "apiKey": "<YOUR_ARK_API_KEY>"
      }
    }
  }
}

在这种情况下，您不需要在服务器环境中设置 GEMINI_API_KEY / ARK_API_KEY 环境变量。

6.3 tools_config.json 示例：Azure OpenAI（LLM + 嵌入）

Azure 要求 api_version 和 azure_endpoint。由于服务请求不暴露这些字段，因此您可以在 tools_config.json 中进行手动配置：

注意：请求中不支持覆盖这些值，因此如果需要不同的 Azure 配置，您需要预先配置好工具的配置文件，而不是在请求中传递。

{
  "tool_name": "action_generator",
  "provider": "azure",
  "model_name": "gpt-4o",
  "api_version": "2024-10-21",
  "azure_endpoint": "https://<your-resource-name>.openai.azure.com",
  "rate_limit": 60
}

所需环境变量：

AZURE_OPENAI_API_KEY
AZURE_OPENAI_ENDPOINT
OPENAI_API_VERSION

注意：您可以选择使用环境变量或工具配置来设置端点/版本，但它们必须在运行时可用。

6.4 tools_config.json 示例：本地 vLLM

{
  "tool_name": "action_generator",
  "provider": "vllm",
  "model_name": "qwen2.5-vl",
  "base_url": "http://127.0.0.1:8000/v1"
}

或者，设置 vLLM_ENDPOINT_URL=http://127.0.0.1:8000/v1。

7) 注意事项与故障排除

如果出现 engine_type is not supported错误，则可能是 provider 字符串与第 2 节中列出的支持值不匹配。
如果出现缺少密钥的错误，请确认第 3 节中提供商的环境变量已设置（并且 .env 文件已被加载）。
对于 gRPC：全局配置变更接口（SetGlobalCommonConfig，SetGlobalCommonLLMConfig 等）需要设置 ALLOW_SET_GLOBAL_CONFIG=1。

本页内容