OneAPI 模型映射配置完全指南：渠道模型名不一致时一步到位改过来-港品优选

OneAPI 模型映射配置完全指南：渠道模型名不一致时一步到位改过来

【免费下载链接】one-apiLLM API 管理 & 分发系统，支持 OpenAI、Azure、Anthropic Claude、Google Gemini、DeepSeek、字节豆包、ChatGLM、文心一言、讯飞星火、通义千问、360 智脑、腾讯混元等主流模型，统一 API 适配，可用于 key 管理与二次分发。单可执行文件，提供 Docker 镜像，一键部署，开箱即用。LLM API management & key redistribution system, unifying multiple providers under a single API. Single binary, Docker-ready, with an English UI.项目地址: https://gitcode.com/GitHub_Trending/on/one-api

有用户按文档请求gpt-3.5-turbo-0301，你的渠道上游只认gpt-3.5-turbo，结果渠道列表里明明有可用渠道，接口却回了一行"当前分组下对于模型 gpt-3.5-turbo-0301 无可用渠道"。问题不在渠道，而在模型名对不上。OneAPI 的模型映射就是为这种"用户请求的模型名"和"上游实际模型名"不一致的场景准备的。

映射在机制层面做了什么

本质是渠道级的一张"模型名翻译表"：请求进来时，OneAPI 把请求体里的模型名查一次表，命中就换成表里的新名字再发给上游，没命中就原样透传。

客户端不用改：用户继续用旧模型名，你换上游版本或改模型版本时无需通知所有人
一个渠道一套表：映射挂在渠道维度，不同渠道可以指向各自的上游真实模型
只改名不改逻辑：请求体其余字段不受影响，但注意映射生效时请求体会被重新构造而非直接透传

在渠道编辑弹窗里加映射

登录管理后台，进入渠道管理，选中目标渠道点编辑。为什么是渠道维度：映射表存在渠道记录里，只对这条渠道的请求生效。
找到模型映射输入框，填入 JSON 格式的"请求名 → 实际名"键值对。为什么用 JSON：键即匹配条件、值即替换结果，语义和代码里的查表逻辑一一对应。
保存前确认输入是合法 JSON，前端会直接校验报错。
用请求模型名发一条真实调用，在日志里确认转发到上游的是映射后的名字。

不走界面的方式

映射就是渠道表的model_mapping字段（varchar(1024)），内容为同样的 JSON 字符串，解析逻辑在model/channel.go的GetModelMapping()里。理解这个函数后，你就能直接判断什么输入是非法的。

请求从进门到出发的链路

关键的翻译动作就一行，在relay/controller/helper.go：

func getMappedModelName(modelName string, mapping map[string]string) (string, bool) { if mapping == nil { return modelName, false } mappedModelName := mapping[modelName] if mappedModelName != "" { return mappedModelName, true } return modelName, false }

注意两点：mapping == nil时直接原样返回，空映射不产生任何开销；匹配是字符串全等，gpt-4不会命中键gpt-4-0314。替换发生在 text、image 等 Relay 控制器里，之后 Adaptor 用替换后的名字拼上游 URL。

映射不生效时按这个表查

症状	大概率原因	验证与修复
映射没替换，上游收到原名	JSON 格式非法，整张表被当空表丢弃；或模型名与键不是全等	保存时前端会提示"模型映射必须是合法的 JSON 格式"，先看弹窗报错；再用 curl 按请求模型名直测，对照日志里`request model`与上游实际模型
报"当前分组下对于模型 xxx 无可用渠道"	渠道选路在映射之前，用用户请求的原始模型名匹配渠道模型列表	确认该渠道的模型列表里包含用户请求的那个名字，映射表只负责转发后改名，不负责选路
之前透传没问题的字段现在丢了	映射生效时请求体被重新构造，个别未正式支持的字段传不上去	能不开映射就不开；确实要改名的，精简请求字段再测一遍

上线前过一遍

✅ 没必要的映射别配：README 明确建议"如无必要请不要设置"
✅ 渠道模型列表包含用户请求的原始模型名（选路依据）
✅ 映射 JSON 通过前端校验，键值与上游真实模型名逐字符核对
✅ 用最小请求实测一次完整链路，看日志确认上游收到的模型名
✅ 上线后清理已失效的模型名映射，保持表精简

更多细节可以看仓库里的 docs/API.md，遇到行为不符合预期就去提 issue。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析