fix: 修复自部署模型渠道 fetch failed 与官方地址测试 404 兼容问题

[ljluestc]

fix: 修复自部署模型渠道 fetch failed 与官方地址测试 404 兼容问题

Closes: #6525

问题背景

用户反馈了两个自部署场景下的问题：

1. 渠道管理页面报错: 未配置 AI Proxy 时访问渠道管理页面出现 "fetch failed" 错误，缺少明确的配置指引

2. 官方 API 地址测试失败: 在模型配置中填写完整的 OpenAI 接口地址（如 https://api.openai.com/v1/chat/completions）测试时返回 404 错误

解决方案

1. 增强 AI Proxy 错误处理

• 未配置 AI Proxy 时返回结构化错误信息，提示用户使用自定义请求地址作为替代方案
• 网络错误时提供可操作的配置诊断信息（Docker 网络问题、TLS 配置建议等）

2. 支持自定义请求地址测试

• 模型测试 API 支持直接使用 requestUrl/requestAuth 参数进行测试，无需依赖 AI Proxy

3. base_url 自动规范化

• 提交渠道配置前自动移除常见 API 路径后缀：
  • /chat/completions
  • /embeddings
  • /audio/transcriptions
  • /audio/speech
  • /rerank
  • /responses
• 避免用户误填完整接口路径导致的 404 问题

4. 改进配置文档

• .env.template 中 AI Proxy 配置标记为可选
• 默认值从 https://localhost:3010 改为 http://localhost:3010，避免本地 TLS 误配

5. 新增使用文档

• 添加「不使用 AI Proxy 的配置方法」文档（中英文双语）
• 详细说明直接使用官方 API 的配置步骤

变更文件

文件路径	变更说明
projects/app/src/pages/api/aiproxy/[...path].ts	增强错误处理，返回结构化错误信息
projects/app/src/pages/api/core/ai/model/test.ts	支持自定义请求地址测试
projects/app/src/pageComponents/account/model/Channel/index.tsx	添加 AI Proxy 错误警告组件
projects/app/src/web/core/ai/channel.ts	添加 normalizeChannelBaseUrl() 规范化函数
projects/app/.env.template	改进 AI Proxy 配置注释
document/content/docs/self-host/config/model/intro.mdx	中文文档
document/content/docs/self-host/config/model/intro.en.mdx	英文文档

测试验证

• 未配置 AI Proxy 时访问渠道管理页面，显示清晰错误提示
• 使用官方 API 地址测试模型连接成功
• base_url 包含完整路径时自动规范化

使用说明

方式一：使用 AI Proxy（推荐）

适用于需要负载均衡、日志记录等高级功能的场景：

AIPROXY_API_ENDPOINT=http://your-aiproxy-host:3010
AIPROXY_API_TOKEN=your-token

方式二：直接使用官方 API

无需配置 AI Proxy，直接在模型配置中设置：

• requestUrl: API 基础地址，如 https://api.openai.com/v1
• requestAuth: API Key

技术细节

base_url 规范化逻辑

// 用户输入: https://api.openai.com/v1/chat/completions
// 规范化后: https://api.openai.com/v1

const channelApiEndpointSuffixList = [
  '/chat/completions',
  '/embeddings',
  '/audio/transcriptions',
  '/audio/speech',
  '/rerank',
  '/responses'
];

错误信息示例

{
  "success": false,
  "message": "AI Proxy request failed (AIPROXY_API_ENDPOINT=http://localhost:3010): connect ECONNREFUSED 127.0.0.1:3010. If FastGPT runs in Docker, localhost points to the FastGPT container itself. Use a container service name or a reachable host IP.",
  "data": null
}

[cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}