把 HK-4.5 接进国内业务，卡住大多数人的不是模型能力，而是三件小事：Base URL 填什么、API Key 怎么带、流式输出为什么没有边出边显示。这三处对齐，接入基本就通了。

这篇教程按“准备—配置—验证—排查”的顺序，把 HK-4.5 在国内 API 接入过程中的关键配置项拆开讲。需要提前说明：文中出现的接口地址、模型名称、计费与额度规则都属于示例结构，请以你所使用平台控制台的实际显示为准，不要直接照抄。

一、先搞清“国内 API 接入”到底在解决什么

很多人以为接入难在模型本身，其实难在三层适配。先理解这三层，配置时才知道自己在改什么。

• 链路层：请求要能从你的服务器或本地环境稳定到达接口端点。直连境外服务时，容易出现握手超时、长连接被中断、流式响应中途断开等情况，这也是不少团队选择中转入口的原因。
• 协议层：目前主流工具链默认按 OpenAI 兼容协议组织请求，也就是 /v1/chat/completions 这类路径、Authorization: Bearer 鉴权、SSE 流式返回。目标端点只要兼容这套协议，迁移成本就主要是改地址和模型名。
• 管理层：如果同时接多家厂商，就会有多个 Key、多份账单、多个控制台。把调用收敛到统一入口之后，Key 轮换、用量核对、额度告警都省事得多。

一个 Base URL 接多模型、统一管理 API Key，是当前 通联AI中转站 这类聚合入口的主要使用方式。是否需要走到这一步，取决于你要接的模型数量和团队规模，不必为了聚合而聚合。

二、配置前需要准备的清单

必须提前拿到的四项信息

1. Base URL：接口根路径，注意它通常只到版本号为止，不包含具体方法名。
2. API Key：在控制台创建，创建后只显示一次，建议立刻存入环境变量或密钥管理服务。
3. 模型名称：请求体里 model 字段要填的值，必须从模型列表里复制，不要凭记忆拼写。
4. 兼容协议类型：确认端点是 OpenAI 兼容、Anthropic 兼容还是其他协议，这决定请求体结构和鉴权头的写法。

环境侧的准备

先在本地用 curl 跑通最小请求，再改代码，能省掉大量“到底是网络问题还是代码问题”的猜测。如果要做流式输出，客户端需要具备按行读取 SSE 的能力；如果链路中间还有自建网关或反向代理，要确认它没有开启响应缓冲。

三、Base URL：写对根路径比写对域名更重要

Base URL 的作用是提供拼接起点。SDK 或 HTTP 客户端会在它后面补上 /chat/completions 之类的路径。所以配置里应该只填到版本号，例如：

Base URL: https://<控制台提供的接入地址>/v1 Model: <从模型列表复制的模型名称> API Key: <控制台创建的 Key>

几个高频错误值得单独列出来：

• 把完整的 /v1/chat/completions 当作 Base URL 填进去，最终拼成重复路径，返回 404。
• 末尾多写或少写斜杠，部分框架会把斜杠当成路径的一部分。
• 混用 http 与 https，或被公司网络策略拦截。
• 把带查询参数的临时地址写进代码，过一段时间就失效。

如果你同时要接多个模型，可以把 通联AI中转站 作为统一入口：地址、Key、模型名都在控制台里拿到，切换模型时通常只改 model 字段。至于该平台上是否有你需要的 HK-4.5 或对应版本，请以模型广场的实时列表和文档说明为准，不要依据第三方说法配置。

四、鉴权：API Key 的带法与安全边界

无论你用 SDK 还是裸 HTTP，Key 最终都会变成请求头里的 Authorization: Bearer <你的Key>。区别在于管理方式。

安全提示：Key 一旦出现在前端页面、公开仓库或日志文件里，就应视为已泄露。请立即在控制台撤销并重建，而不是只做删除处理。

五、流式输出思路：协议对了，体验才顺畅

服务端侧要确认的三件事

• 请求体里 stream 设为 true，返回内容类型通常是 text/event-stream。
• 数据以 data: {...} 的形式分块下发，结束时返回 data: [DONE]。
• 如果中间有 Nginx 或自建网关，需要关闭响应缓冲，否则内容会攒到最后一次性吐出。

客户端侧要处理的三个边界

第一，按行缓冲解析，不要假设一次读取就是一条完整消息，网络分片会把一条 JSON 拆成两半。第二，把读取超时设置得比非流式更长，或者依赖心跳判断连接是否存活。第三，收到 [DONE] 后再收尾，不要在第一个分片就认为请求结束。下面是最小验证逻辑，只关注结构：

# 非流式：确认鉴权与模型名正确 curl -s -X POST "$BASE_URL/chat/completions" \ -H "Authorization: Bearer $API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"MODEL_NAME","messages":[{"role":"user","content":"hi"}]}' # 流式：确认逐块返回 # 在请求体中加上 "stream": true 后重跑一次

两条命令都通，说明链路、鉴权、模型名、协议四件事基本没问题，剩下的就是业务代码适配。

六、上线前的最小验证流程

1. 用最短请求确认接口可达，返回结构符合预期。
2. 发一条非流式请求，记录响应时间与 token 用量。
3. 开启流式，观察首字返回时间与是否逐段输出。
4. 发一段长文本，验证长响应下连接不会中断。
5. 把超时、重试、错误日志接入监控，再切到正式流量。

七、常见报错与排查顺序

遇到问题先别动代码，按“地址—鉴权—模型—网络”的顺序逐层排除：401/403 多半是 Key 错误或未带 Bearer 前缀；404 通常是 Base URL 路径拼接问题；模型不存在类 400 说明 model 字段与平台列表不一致；429 涉及限流或额度，需要到控制台核对用量；超时或中途断开 优先检查代理缓冲与读超时设置。

把这几层跑通之后，HK-4.5 的国内 API 接入就不再是一次性的“调通就行”，而是可以沉淀成配置项、随模型切换复用的标准流程。相关地址、模型名称、计费与额度说明，都可以在 通联AI中转站官网 的控制台与文档中核对。