如何为Chat API添加一个新的大模型上游渠道适配器开发实战教程【免费下载链接】chat-apiOpenAI 接口聚合管理我们致力于提供优质的API接入服务让您可以轻松集成先进的AI模型至您的产品和服务。项目地址: https://gitcode.com/gh_mirrors/ch/chat-apiChat API 是一个OpenAI 接口聚合管理平台它把各家大模型厂商的接口统一封装成 OpenAI 兼容格式让开发者用一把 Token 就能调用 Gemini、Claude、文心一言等上游模型。如果你想把新的上游比如 Ollama、Cohere、DeepSeek接入 Chat API核心工作就是开发一个渠道适配器Channel Adaptor它负责把统一的 OpenAI 请求翻译成目标上游的私有协议再把响应翻译回来。本教程将以真实源码为例带你走完从定义渠道编号、实现适配器、注册系统到控制台测试的完整流程。一、先搞懂渠道适配器在整个项目中扮演什么角色Chat API 的转发逻辑集中在relay/目录一次请求的处理链路大致是用户请求 → 路由与中间件router/relay-router.go→ 选择渠道middleware/distributor.go→渠道适配器relay/channel/下的各家子目录→ 上游模型每个上游厂商的 API 协议都不同鉴权方式、请求体字段、流式返回格式各不相同而 Chat API 对外只暴露统一的 OpenAI 格式。渠道适配器就是中间的翻译官所有协议差异都被隔离在适配器内部。relay/channel/下已经内置了几十种渠道可以作为现成参考适配器目录对接的上游relay/channel/openai/OpenAI / Azure / 各种 OpenAI 兼容服务relay/channel/anthropic/Clauderelay/channel/gemini/Google Geminirelay/channel/baidu/百度文心一言relay/channel/ollama/Ollama 本地大模型relay/channel/coze/字节 Coze新手建议写新适配器前先找一个和目标上游协议最像的现有适配器通读一遍比看文档快得多。二、新渠道接入的完整路径一共要改哪 5 处步骤文件做什么① 定义渠道类型common/constants.go新增ChannelTypeXxx编号并加入ChannelBaseURLs列表② 映射 API 类型relay/constant/api_type.go在ChannelType2APIType中把渠道号映射为APITypeXxx③ 实现适配器relay/channel/ 下新建目录实现Adaptor接口完成请求/响应转换④ 注册适配器relay/helper/main.go在GetAdaptor的 switch 中返回你的适配器实例⑤ 控制台配置测试管理后台渠道管理添加渠道、填写 BaseURL 与 API Key、点击测试以渠道编号为例在 common/constants.go 中可以清晰看到编号是顺序分配的ChannelTypeOllama 33 ChannelTypeAwsClaude 35 ChannelTypeCoze 36 // 新增渠道时取下一个未使用的编号即可同时需要把新渠道的默认 BaseURL 追加到同文件的ChannelBaseURLs数组中这样前端创建渠道时会自动带出正确的默认地址。三、适配器接口详解需要实现的 9 个方法所有适配器都要实现统一接口定义在 relay/channel/interface.gotype Adaptor interface { Init(meta *util.RelayMeta) GetRequestURL(meta *util.RelayMeta) (string, error) SetupRequestHeader(c *gin.Context, req *http.Request, meta *util.RelayMeta) error ConvertRequest(c *gin.Context, meta *util.RelayMeta, request *model.GeneralOpenAIRequest) (any, error) ConvertImageRequest(request *model.ImageRequest) (any, error) DoRequest(c *gin.Context, meta *util.RelayMeta, requestBody io.Reader) (*http.Response, error) DoResponse(c *gin.Context, resp *http.Response, meta *util.RelayMeta) (aitext string, usage *model.Usage, err *model.ErrorWithStatusCode) GetModelList() []string GetChannelName() string }各方法的职责可以这样记忆Init初始化比如按模型名选择不同协议版本GetRequestURL根据meta.Mode对话/向量化/图像生成等定义见 relay/constant/relay_mode.go拼出上游完整 URLSetupRequestHeader设置鉴权头Bearer、AK/SK 签名等ConvertRequest/ConvertImageRequest把 OpenAI 请求体转成上游私有格式DoRequest发送 HTTP 请求一般直接调用通用辅助函数DoResponse解析上游响应回填 token 用量usage这是计费的关键GetModelList/GetChannelName返回模型清单与渠道名称 其中DoRequest几乎不需要自己写直接复用 relay/channel/common.go 中的DoRequestHelper即可它会自动处理 URL 拼接、请求头设置和代理转发配合common/client/proxy.go的代理能力。四、以 Ollama 为例写出一个最小可用适配器Ollama 适配器relay/channel/ollama/是代码量最少的完整样例非常适合新手仿写。它的目录结构就是新渠道的标准模板adaptor.go—— 实现Adaptor接口constants.go—— 定义ModelList模型清单model.go—— 定义上游的请求/响应结构体main.go—— 响应解析流式与非流式① 核心逻辑只有几十行看 relay/channel/ollama/adaptor.go 的两个关键方法func (a *Adaptor) GetRequestURL(meta *util.RelayMeta) (string, error) { fullRequestURL : fmt.Sprintf(%s/api/chat, meta.BaseURL) if meta.Mode constant.RelayModeEmbeddings { fullRequestURL fmt.Sprintf(%s/api/embeddings, meta.BaseURL) } return fullRequestURL, nil } func (a *Adaptor) SetupRequestHeader(c *gin.Context, req *http.Request, meta *util.RelayMeta) error { channel.SetupCommonRequestHeader(c, req, meta) req.Header.Set(Authorization, Bearer meta.APIKey) return nil }② 用结构体描述上游协议在 relay/channel/ollama/model.go 中type ChatRequest struct { Model string json:model,omitempty Messages []Message json:messages,omitempty Stream bool json:stream Options *Options json:options,omitempty }③ 在ConvertRequest中做字段映射把统一的GeneralOpenAIRequest定义于 relay/model/general.go逐字段转换成ChatRequest。④ 在DoResponse中按meta.IsStream分支处理流式/非流式响应并把prompt_eval_count/eval_count换算为usage保证账单准确。⚠️ 注意如果上游的 token 计费口径与 OpenAI 不同建议在 relay/util/model_mapping.go 中配置模型映射而不是在适配器里硬编码。五、把新渠道注册进系统适配器写好后还差两步注册① 在 relay/helper/main.go 的GetAdaptor中注册——这是系统根据 API 类型找到适配器的唯一入口case constant.APITypeOllama: return ollama.Adaptor{}② 在 relay/constant/api_type.go 中完成渠道号 → API 类型的映射并新增对应的APITypeXxx常量。小技巧如果你的目标上游兼容 OpenAI 协议则无需新写适配器直接在控制台创建OpenAI类型渠道、填入它的 BaseURL 即可这正是 relay/channel/openai/compatible.go 支持的能力。六、在控制台添加并测试你的新渠道代码改完、服务重启后进入管理后台的渠道管理页面操作步骤点击右上角添加渠道类型选择你新增的渠道类型填写上游BaseURL与API Key本地模型如 Ollama 通常无需 Key在模型栏粘贴你的模型清单来自适配器的ModelList点击测试按钮验证连通性成功后开启渠道并配置分组与权重测试通过后该上游的模型就会出现在用户侧的模型列表中统一以 OpenAI 兼容格式对外服务 七、最佳实践与避坑清单流式响应是最容易踩坑的部分不同上游的 SSE 结束标记不同[DONE]vsdone: true务必参考 relay/channel/ollama/main.go 中StreamHandler的逐行解析方式错误码要规范统一用model.ErrorWithStatusCode返回让上游 4xx/5xx 能被正确透传并计入渠道健康度计费别漏DoResponse中一定要填充usage否则该渠道请求无法统计 token 消耗计费逻辑见 relay/util/billing.go渠道测试失败会触发自动禁用如果你的上游限流严格测试接口要选轻量模型参考学习路径简单渠道看 relay/channel/ollama/复杂渠道多协议分支看 relay/channel/ali/ 和 relay/channel/coze/小结为 Chat API 添加新的大模型上游本质就是**4 处代码 1 次测试**common/constants.go 中分配渠道编号relay/constant/api_type.go 中映射 API 类型relay/channel/ 下新建目录实现Adaptor接口relay/helper/main.go 中注册适配器控制台添加渠道并测试掌握这套适配器开发流程后你就能把任意协议的大模型服务接入 Chat API让平台的能力随需求无限扩展。【免费下载链接】chat-apiOpenAI 接口聚合管理我们致力于提供优质的API接入服务让您可以轻松集成先进的AI模型至您的产品和服务。项目地址: https://gitcode.com/gh_mirrors/ch/chat-api创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
