{"repo": "artisancloud/powerx", "files": {"docs/guides/agent/ai_setting.md": {"8b845aee0fb1ad928bde2b990b47a885e859f42c": {"t": 1785746494.8433843, "n": 2460, "h": "0ced479adb8c68ad", "c": "# AI 设置与主模型生效流程\n\nPowerX 的「AI 设置」页面提供了统一的 Provider/模型管理;理解其落库与生效顺序,能帮你快速定位“为什么切换 provider 没有真正生效”的问题。\n\n## 默认配置\n\n1. **开发期种子默认值**:`backend/etc/config_example.yaml` 的 `ai.defaults` 主要用于“本地开发/初次启动”的演示默认(例如默认选中哪个 provider/model)。在生产环境里,如果数据库里没有保存任何 AI Settings(含凭据),系统应提示用户先完成安装/配置,而不是静默使用 config.yaml 的值继续执行。\n2. **环境隔离**:页面左侧的环境切换(默认 `default`)会把不同环境的数据保存在各自的 scope 下,后端通过 `env + tenant` 二元索引区分,同一个 provider 可以在不同环境配置不同的 key。\n\n## 聊天时的 LLM 生效优先级(人话版)\n\n一次“发送消息”真正用哪个 provider/model/参数,会按从高到低依次覆盖:\n\n1. **Flow 节点级配置(node params)**:某个 flow 的某个 LLM 节点写死的参数(例如强制 `model=xxx`)。这是最高优先级。\n2. **本次请求临时配置(ChatConfig)**:前端在本次发送里临时指定(例如用户临时切模型/温度),只影响这一次或这一会话。\n3. **智能体自身配置(AgentSetting,DB)**:在「智能体配置」里给某个智能体单独设置的 provider/model(以及可选参数),只影响这个智能体。\n4. **AI Settings 默认(Active Profile,DB)**:在「AI 设置」里选中的默认 provider/model(按 env + tenant 隔离),作为系统默认。\n5. **开发期种子默认(config.yaml)**:仅用于没有任何 DB 配置时的“演示默认”。如果缺少凭据/不可连通,运行时应返回明确错误并引导去 AI Settings 配置。\n\n## 保存一次 = 落两个实体\n\n点击页面的「保存」会触发 `AgentSettingService.SaveCredentialAndProfile`,落库逻辑如下:\n\n| 实体 | 说明 |\n| --- | --- |\n| `ai_provider_credentials` | 记录 provider 的 `base_url`、`api_key` 等敏感字段。重复保存会自动加密并“保留旧的 __sealed”。 |\n| `ai_model_profiles` | 记录当前模态的 provider/model 组合以及默认参数(温度、max_tokens 等)。 |\n\n换句话说,你可以先把不同 provider 的凭据都保存好,作为候选。此时数据库里会有多条 profile/credential,但 Agent 仍然会沿用「当前激活配置」。\n\n## 选择谁当主模型?\n\n真正决定“系统主智能体”使用哪个 provider/model 的,是 `ai_route_policies` 中的默认路由(`SetActiveProfile` 会写入 Name=`__default` 的记录):\n\n1. 在页面切换到目标 provider/model。\n2. (可选)点击「测试连接」保证连通性通过。\n3. 点击「保存」。这一步不仅更新 profile/credential,还会把该 provider/model 写入默认路由,后端随即改用新的组合。\n\n> ⚠️ **仅切换下拉框不生效**:如果你仅切换 provider 但没有点击「保存」,前端状态会改变,但数据库里的默认路由不会更新,Agent 仍然调用旧模型。\n\n## 智能体级覆盖(AgentSetting)\n\n如果你希望某个智能体使用不同于系统默认的模型(例如“营销智能体用 deepseek-reasoner、客服智能体用 gpt-4o-mini”),请在智能体的配置面板里设置 provider/model(并保存)。\n\n- 这会写入 `agent_settings`(按 env + tenant + agent 作用域)\n- 运行时会先读取 AI Settings 的默认,再读取该智能体的覆盖;如果智能体选择“系统默认”,则会删除该覆盖记录并回退到 AI Settings 默认\n\n## 多 provider 场景\n\n- 你可以为多个 provider 各自保存凭据、参数,但同一模态下始终只有一个“激活”组合。需要切换时,选中后再次点击「保存」,系统会覆盖默认路由。\n- 若想恢复默认(或某个候选)配置,只需切到对应 provider,检查参数无误后点击「保存」即可。\n- 删除/禁用某 provider 之前,建议先把默认路由切到其他 provider,避免出现“找不到激活 profile”。\n\n## 常见问题排查\n\n| 现象 | 可能原因 | 处理方式 |\n| --- | --- | --- |\n| 后端日志仍显示旧 provider | 切换后未点击「保存」;或保存失败 | 查看页面提示/浏览器 Network,确认 `…/settings/save` 返回成功 |\n| Base URL 不随 provider 清空 | 老版前端会缓存,记得刷新页面或在「保存」前手动覆盖 | 当前版本已在 provider 切换时同步;若仍遇到,重载页面确认 |\n| 环境切换后配置不对 | 环境 store 未刷新 | 先切换环境,下方状态加载完成后再进行操作 |\n\n掌握上述流程后,可以放心地把多个 provider 的信息一次性录入,只需记得“切换谁 → 就立即保存”来更新默认主模型。 ***\n"}, "bb25e7e153153ac449acc8b957cddf76f565bafa": {"t": 1785764947.6109354, "n": 2460, "h": "0ced479adb8c68ad", "c": "# AI 设置与主模型生效流程\n\nPowerX 的「AI 设置」页面提供了统一的 Provider/模型管理;理解其落库与生效顺序,能帮你快速定位“为什么切换 provider 没有真正生效”的问题。\n\n## 默认配置\n\n1. **开发期种子默认值**:`backend/etc/config_example.yaml` 的 `ai.defaults` 主要用于“本地开发/初次启动”的演示默认(例如默认选中哪个 provider/model)。在生产环境里,如果数据库里没有保存任何 AI Settings(含凭据),系统应提示用户先完成安装/配置,而不是静默使用 config.yaml 的值继续执行。\n2. **环境隔离**:页面左侧的环境切换(默认 `default`)会把不同环境的数据保存在各自的 scope 下,后端通过 `env + tenant` 二元索引区分,同一个 provider 可以在不同环境配置不同的 key。\n\n## 聊天时的 LLM 生效优先级(人话版)\n\n一次“发送消息”真正用哪个 provider/model/参数,会按从高到低依次覆盖:\n\n1. **Flow 节点级配置(node params)**:某个 flow 的某个 LLM 节点写死的参数(例如强制 `model=xxx`)。这是最高优先级。\n2. **本次请求临时配置(ChatConfig)**:前端在本次发送里临时指定(例如用户临时切模型/温度),只影响这一次或这一会话。\n3. **智能体自身配置(AgentSetting,DB)**:在「智能体配置」里给某个智能体单独设置的 provider/model(以及可选参数),只影响这个智能体。\n4. **AI Settings 默认(Active Profile,DB)**:在「AI 设置」里选中的默认 provider/model(按 env + tenant 隔离),作为系统默认。\n5. **开发期种子默认(config.yaml)**:仅用于没有任何 DB 配置时的“演示默认”。如果缺少凭据/不可连通,运行时应返回明确错误并引导去 AI Settings 配置。\n\n## 保存一次 = 落两个实体\n\n点击页面的「保存」会触发 `AgentSettingService.SaveCredentialAndProfile`,落库逻辑如下:\n\n| 实体 | 说明 |\n| --- | --- |\n| `ai_provider_credentials` | 记录 provider 的 `base_url`、`api_key` 等敏感字段。重复保存会自动加密并“保留旧的 __sealed”。 |\n| `ai_model_profiles` | 记录当前模态的 provider/model 组合以及默认参数(温度、max_tokens 等)。 |\n\n换句话说,你可以先把不同 provider 的凭据都保存好,作为候选。此时数据库里会有多条 profile/credential,但 Agent 仍然会沿用「当前激活配置」。\n\n## 选择谁当主模型?\n\n真正决定“系统主智能体”使用哪个 provider/model 的,是 `ai_route_policies` 中的默认路由(`SetActiveProfile` 会写入 Name=`__default` 的记录):\n\n1. 在页面切换到目标 provider/model。\n2. (可选)点击「测试连接」保证连通性通过。\n3. 点击「保存」。这一步不仅更新 profile/credential,还会把该 provider/model 写入默认路由,后端随即改用新的组合。\n\n> ⚠️ **仅切换下拉框不生效**:如果你仅切换 provider 但没有点击「保存」,前端状态会改变,但数据库里的默认路由不会更新,Agent 仍然调用旧模型。\n\n## 智能体级覆盖(AgentSetting)\n\n如果你希望某个智能体使用不同于系统默认的模型(例如“营销智能体用 deepseek-reasoner、客服智能体用 gpt-4o-mini”),请在智能体的配置面板里设置 provider/model(并保存)。\n\n- 这会写入 `agent_settings`(按 env + tenant + agent 作用域)\n- 运行时会先读取 AI Settings 的默认,再读取该智能体的覆盖;如果智能体选择“系统默认”,则会删除该覆盖记录并回退到 AI Settings 默认\n\n## 多 provider 场景\n\n- 你可以为多个 provider 各自保存凭据、参数,但同一模态下始终只有一个“激活”组合。需要切换时,选中后再次点击「保存」,系统会覆盖默认路由。\n- 若想恢复默认(或某个候选)配置,只需切到对应 provider,检查参数无误后点击「保存」即可。\n- 删除/禁用某 provider 之前,建议先把默认路由切到其他 provider,避免出现“找不到激活 profile”。\n\n## 常见问题排查\n\n| 现象 | 可能原因 | 处理方式 |\n| --- | --- | --- |\n| 后端日志仍显示旧 provider | 切换后未点击「保存」;或保存失败 | 查看页面提示/浏览器 Network,确认 `…/settings/save` 返回成功 |\n| Base URL 不随 provider 清空 | 老版前端会缓存,记得刷新页面或在「保存」前手动覆盖 | 当前版本已在 provider 切换时同步;若仍遇到,重载页面确认 |\n| 环境切换后配置不对 | 环境 store 未刷新 | 先切换环境,下方状态加载完成后再进行操作 |\n\n掌握上述流程后,可以放心地把多个 provider 的信息一次性录入,只需记得“切换谁 → 就立即保存”来更新默认主模型。 ***\n"}, "d6561e4c7f788d25d5ac398d31f6f788dcab7df3": {"t": 1785764949.7909915, "n": 1642, "h": "7a2e3d17bd8d6f85", "c": "# AI 设置与主模型生效流程\n\nPowerX 的「AI 设置」页面提供了统一的 Provider/模型管理;理解其落库与生效顺序,能帮你快速定位“为什么切换 provider 没有真正生效”的问题。\n\n## 默认配置\n\n1. **后端默认值**:若从未在后台保存任何配置,Agent 将使用 `backend/etc/config_example.yaml` 中 `ai.defaults` 段配置的 provider / model / endpoint。这是编译期的静态兜底,适合本地开发。\n2. **环境隔离**:页面左侧的环境切换(默认 `default`)会把不同环境的数据保存在各自的 scope 下,后端通过 `env + tenant` 二元索引区分,同一个 provider 可以在不同环境配置不同的 key。\n\n## 保存一次 = 落两个实体\n\n点击页面的「保存」会触发 `AgentSettingService.SaveCredentialAndProfile`,落库逻辑如下:\n\n| 实体 | 说明 |\n| --- | --- |\n| `ai_provider_credentials` | 记录 provider 的 `base_url`、`api_key` 等敏感字段。重复保存会自动加密并“保留旧的 __sealed”。 |\n| `ai_model_profiles` | 记录当前模态的 provider/model 组合以及默认参数(温度、max_tokens 等)。 |\n\n换句话说,你可以先把不同 provider 的凭据都保存好,作为候选。此时数据库里会有多条 profile/credential,但 Agent 仍然会沿用「当前激活配置」。\n\n## 选择谁当主模型?\n\n真正决定“系统主智能体”使用哪个 provider/model 的,是 `ai_route_policies` 中的默认路由(`SetActiveProfile` 会写入 Name=`__default` 的记录):\n\n1. 在页面切换到目标 provider/model。\n2. (可选)点击「测试连接」保证连通性通过。\n3. 点击「保存」。这一步不仅更新 profile/credential,还会把该 provider/model 写入默认路由,后端随即改用新的组合。\n\n> ⚠️ **仅切换下拉框不生效**:如果你仅切换 provider 但没有点击「保存」,前端状态会改变,但数据库里的默认路由不会更新,Agent 仍然调用旧模型。\n\n## 多 provider 场景\n\n- 你可以为多个 provider 各自保存凭据、参数,但同一模态下始终只有一个“激活”组合。需要切换时,选中后再次点击「保存」,系统会覆盖默认路由。\n- 若想恢复默认(或某个候选)配置,只需切到对应 provider,检查参数无误后点击「保存」即可。\n- 删除/禁用某 provider 之前,建议先把默认路由切到其他 provider,避免出现“找不到激活 profile”。\n\n## 常见问题排查\n\n| 现象 | 可能原因 | 处理方式 |\n| --- | --- | --- |\n| 后端日志仍显示旧 provider | 切换后未点击「保存」;或保存失败 | 查看页面提示/浏览器 Network,确认 `…/settings/save` 返回成功 |\n| Base URL 不随 provider 清空 | 老版前端会缓存,记得刷新页面或在「保存」前手动覆盖 | 当前版本已在 provider 切换时同步;若仍遇到,重载页面确认 |\n| 环境切换后配置不对 | 环境 store 未刷新 | 先切换环境,下方状态加载完成后再进行操作 |\n\n掌握上述流程后,可以放心地把多个 provider 的信息一次性录入,只需记得“切换谁 → 就立即保存”来更新默认主模型。 ***\n"}}, "backend/config/agents/providers.d/hunyuan.yaml": {"8b845aee0fb1ad928bde2b990b47a885e859f42c": {"t": 1785809844.3322086, "n": 3804, "h": "ab9488a2813c7892", "c": "id: hunyuan\nname: 腾讯混元 (Hunyuan)\naliases:\n # “元宝”是产品侧名称,这里作为别名兼容历史配置/输入\n - \"Hunyuan\"\n - \"hunyuan\"\n - \"腾讯混元\"\n - \"Tencent Hunyuan\"\n - \"Yuanbao\"\n - \"yuanbao\"\n - \"腾讯元宝\"\n - \"Tencent Yuanbao\"\n\ndrivers:\n llm: hunyuan\n image: external\n video: external\n\nauth:\n # 同时支持两种接入方式:\n # 1) OpenAI SDK 兼容:API KEY(优先推荐,前端默认)\n # 2) 腾讯云 SDK:SecretId/SecretKey(TC3 签名)\n modes:\n - id: openai\n label: \"OpenAI SDK(API Key)\"\n scheme: bearer\n fields: [\"api_key\", \"base_url\"]\n defaults:\n # 腾讯云大模型 API(OpenAI SDK 兼容)\n base_url: \"https://api.hunyuan.cloud.tencent.com/v1\"\n - id: tc3\n label: \"腾讯云 SDK(SecretId/SecretKey)\"\n scheme: tc3\n fields: [\"secret_id\", \"secret_key\", \"region\", \"base_url\"]\n defaults:\n base_url: \"https://hunyuan.tencentcloudapi.com\"\n region: \"ap-guangzhou\"\n\nmodalities:\n llm:\n note: \"目录占位:用于在 UI 中预置混元模型列表;实际调用需要补齐 llm driver(或接入 OpenAI-compatible 网关)。\"\n models:\n - id: hunyuan-lite\n label: \"混元 Lite (placeholder)\"\n tags: [\"llm\",\"tencent\",\"placeholder\"]\n defaults:\n temperature: 0.7\n max_tokens: 1024\n # OpenAI SDK 模式的 base_url 默认带 /v1,因此这里用相对路径\n api_path: \"/chat/completions\"\n - id: hunyuan-standard\n label: \"混元 Standard (placeholder)\"\n tags: [\"llm\",\"tencent\",\"placeholder\"]\n defaults:\n temperature: 0.7\n max_tokens: 2048\n api_path: \"/chat/completions\"\n - id: hunyuan-standard-256K\n label: \"混元 Standard 256K (placeholder)\"\n tags: [\"llm\",\"tencent\",\"placeholder\",\"long-context\"]\n defaults:\n temperature: 0.6\n max_tokens: 4096\n api_path: \"/chat/completions\"\n - id: hunyuan-turbo\n label: \"混元 Turbo (placeholder)\"\n tags: [\"llm\",\"tencent\",\"placeholder\"]\n defaults:\n temperature: 0.7\n max_tokens: 1024\n api_path: \"/chat/completions\"\n - id: hunyuan-turbo-latest\n label: \"混元 Turbo Latest (placeholder)\"\n tags: [\"llm\",\"tencent\",\"placeholder\"]\n defaults:\n temperature: 0.7\n max_tokens: 1024\n api_path: \"/chat/completions\"\n - id: hunyuan-pro\n label: \"混元 Pro (placeholder)\"\n tags: [\"llm\",\"tencent\",\"placeholder\"]\n defaults:\n temperature: 0.6\n max_tokens: 2048\n api_path: \"/chat/completions\"\n - id: hunyuan-code\n label: \"混元 Code (placeholder)\"\n tags: [\"llm\",\"tencent\",\"placeholder\",\"code\"]\n defaults:\n temperature: 0.3\n max_tokens: 2048\n api_path: \"/chat/completions\"\n\n model3d:\n note: \"腾讯混元 3D 生成模型(UI 目录)。\"\n models:\n - id: HY-3D-Express\n label: \"HY-3D-Express\"\n tags: [\"3d\",\"tencent\",\"hunyuan\"]\n - id: HY-3D-UVWrap-1.5\n label: \"HY-3D-UVWrap-1.5\"\n tags: [\"3d\",\"tencent\",\"hunyuan\"]\n - id: HY 3D Texture Generation\n label: \"HY 3D Texture Generation\"\n tags: [\"3d\",\"tencent\",\"hunyuan\",\"texture\"]\n - id: HY 3D Smart Topology\n label: \"HY 3D Smart Topology\"\n tags: [\"3d\",\"tencent\",\"hunyuan\",\"topology\"]\n - id: HY 3D Part Generation\n label: \"HY 3D Part Generation\"\n tags: [\"3d\",\"tencent\",\"hunyuan\",\"part\"]\n - id: HY-3D-Profession\n label: \"HY-3D-Profession\"\n tags: [\"3d\",\"tencent\",\"hunyuan\"]\n\n image:\n note: \"目录占位:用于在 UI 中预置混元图像生成入口;实际调用需要补齐 image driver。\"\n models:\n - id: hunyuan-image\n label: \"混元 图像生成 (placeholder)\"\n tags: [\"image\",\"tencent\",\"placeholder\"]\n\n video:\n note: \"目录占位:用于在 UI 中预置混元视频生成入口;实际调用需要补齐 video driver。\"\n models:\n - id: hunyuan-video\n label: \"混元 视频生成 (placeholder)\"\n tags: [\"video\",\"tencent\",\"placeholder\"]\n\n audio_tts:\n models: []\n\n audio_asr:\n models: []\n"}}, "web-admin/app/pages/setup/index.vue": {"8b845aee0fb1ad928bde2b990b47a885e859f42c": {"t": 1785809848.2178767, "n": 92937, "h": "d95a9f03385b26cd", "c": "\n\n\n"}}}}