文心快码混合云部署安装配置详细步骤

混合云部署这件事，听起来复杂，其实拆开来看就几步：先搞定企业认证和API权限，再下载安装包、配好运行环境，然后写入密钥、设置模型路由，最后启动服务验证一下。下面按顺序说清楚每一步的关键细节。

确认混合云部署前提条件

要在本地服务器与百度智能云文心千帆平台之间建立一条安全、可控的混合云调用链路，企业级账号实名认证、API权限开通、网络策略放行这三件事，一个都不能少。哪一步卡住了，后续安装就白费功夫。

具体操作：登录百度智能云控制台 → 进入「组织管理」→ 完成企业实名认证（需要营业执照扫描件+法人身份证）→ 然后在「访问控制RAM」中为部署账号授予两个系统策略：QwenComateFullAccess 和 WenxinWorkshopInvokeFullAccess。

必须注意：本地防火墙的出站规则如果限制太严，SDK就没法连上文心千帆API网关。所以一定得先放行，否则后面全是错误。

下载并校验文心快码混合云安装包

访问百度智能云「文心快码（Comate）」产品页，点击「混合云部署」标签，根据你的操作系统选择下载：Windows用 comate-hybrid-v3.2.1-win-amd64.zip，Linux用 comate-hybrid-v3.2.1-linux-x86_64.tar.gz。

下载完成后，别急着解压，先校验完整性。Windows用户打开PowerShell，执行 Get-FileHash -Algorithm SHA256 comate-hybrid-v3.2.1-win-amd64.zip；Linux用户执行 sha256sum comate-hybrid-v3.2.1-linux-x86_64.tar.gz。算出来的哈希值跟官网公布的一模一样才算通过——只要有一点差异，直接删掉重下。

配置本地运行环境

方法一：Windows系统（推荐）

先安装 .NET Runtime 8.0（注意是Runtime，不是SDK），再装Visual C++ 2019可再发行组件包（x64）。把安装包解压到非系统盘路径，比如 D:\comate-hybrid。进入 config 目录，用记事本打开 appsettings.json，把 "CloudEndpoint" 的值改成 "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/comate/hybrid"。

方法二：Linux系统（CentOS 7+/Ubuntu 22.04+）

Ubuntu下执行 sudo apt update && sudo apt install -y libunwind8 libicu72；CentOS下执行 sudo yum install -y libunwind libicu。然后创建一个专用用户 sudo useradd -m -s /bin/bash comate，切换到这个用户，把安装包解压到 /opt/comate-hybrid。最后修改 config/appsettings.json 中的 "LocalMode" 值为 true。

初始化混合云密钥与模型路由

第一步：获取AK/SK凭证

回到百度智能云控制台，进入「AccessKey管理」，创建一个新的AK/SK。生成的 AccessKeyId 和 SecretKey 务必复制保存到安全的地方——这个操作不可逆，丢了就只能重新创建。

第二步：写入密钥配置

在安装包根目录下新建一个纯文本文件，文件名就叫 credentials（不要扩展名）。写入以下内容：

[default]
ak = 【你的AccessKeyId】
sk = 【你的SecretKey】
region = bj

第三步：绑定模型路由策略

编辑 config/model-routing.json，把默认的 "fallback_model" 改成 "ernie-4.5t-pro"。然后在 "rules" 数组里加一条策略：{"pattern": ".*ja va.*", "model": "ernie-x1t-ja va"}。这条规则的作用是：自动识别Ja va代码请求，并路由到专用的小模型上，提高效率和针对性。

启动服务并验证连通性

Windows下以管理员身份运行 start-service.bat；Linux下执行 sudo ./start-service.sh。

服务启动后，等大约12秒，然后检查日志文件。Windows看 logs\startup.log，Linux看 logs/startup.log。重点找两行关键信息：Hybrid gateway initialized successfully 和 Connected to Wenxin Qianfan API: OK。缺一不可。

最后在本地终端执行一条curl命令来验证：curl -X POST "http://localhost:8080/v1/chat/completions" -H "Content-Type: application/json" -d '{"messages":[{"role":"user","content":"测试"}]}'。如果返回的JSON里包含 "choices" 字段，恭喜，混合云部署已经就绪。