# ZCode
ZCode是智谱AI（Z.ai）推出的Agentic Development Environment（ADE，智能体开发环境），深度适配GLM-5.2大模型，支持1M长上下文，能够从需求理解、计划拆解到代码修改和验证收口的全流程开发。ZCode还支持接入MaaS模型API，从而提供更多可选择的模型。本文主要介绍如何配置MaaS模型API。
#### 前提条件
- 已注册华为云账号，并进行实名认证。具体操作，请参见[注册华为云账号](https://support.huaweicloud.com/usermanual-account/account_id_001.html)和[实名认证](https://support.huaweicloud.com/usermanual-account/zh-cn_topic_0071343161.html)。
- 已开通预置服务，或已创建接入点。具体操作，请参见[开通预置服务](https://support.huaweicloud.com/console-functions-maas/maas_0003.html#section4)或[创建自定义接入点](https://support.huaweicloud.com/console-functions-maas/maas_0004.html#section3)。
 
#### 计费说明
在调用MaaS模型服务时，将根据实际使用的Tokens数量进行计费。计费详情请参见[MaaS文本生成模型](https://support.huaweicloud.com/price-maas/price-maas-0002.html)。
#### 约束限制
该功能仅支持"西南-贵阳一"区域。
#### 步骤一：安装ZCode
在[ZCode官网](https://zcode.z.ai/cn)下载并安装对应操作系统的版本。ZCode支持macOS、Windows和Linux。
安装完成后，打开ZCode，可选择连接Z.ai账号、BigModel账号或使用API Key接入模型。本文以使用API Key接入MaaS模型为例。
 #### 步骤二：接入MaaS模型API
1. 打开ZCode，在对话框下方单击模型选择器，选择"管理模型"。如下图所示： 
   图1打开模型设置页面   
   ![](https://support.huaweicloud.com/access-tools-maas/figure/zh-cn_image_0000002792120791.png "点击放大")
   
   
   
2. 进入"模型设置"页面，在右上角单击"添加供应商"，选择"创建自定义供应商"，如图所示： 
   图2添加供应商   
   ![](https://support.huaweicloud.com/access-tools-maas/figure/zh-cn_image_0000002792122089.png "点击放大")
   
   
   
3. 在"添加供应商"页面，参考下表配置。 
   图3设置自定义供应商   
   ![](https://support.huaweicloud.com/access-tools-maas/figure/zh-cn_image_0000002763979998.png "点击放大")
   
   表1自定义供应商配置 
   | 参数        | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | 示例                                     |
   |:---|:---|:---|
   | 供应商名称 | 自定义供应商名称。 单击右上角![](https://support.huaweicloud.com/access-tools-maas/figure/zh-cn_image_0000002793460115.png)，选择"重命名"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | 华为云MaaS                                |
   | Base URL | 必填。 - Chat Completions格式，路径如下： - https://api.modelarts-maas.com/v2    - https://api.modelarts-maas.com/openai/v1    - Anthropic Messages格式，路径如下： https://api.modelarts-maas.com/anthropic    | https://api.modelarts-maas.com/openai/v1 |
   | API格式   | 必填。 - Chat Completions格式  - Anthropic Messages格式                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | 选择Chat Completions格式                      |
   | API Key   | 必填。 可使用已有的API Key，如果没有可[获取API Key](https://console.huaweicloud.com/modelarts/#/model-studio/authmanage)。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | gA4ocs\*\*\*\*\*Tc-Kz4AQ                 |
      
   
   
4. 单击"添加模型"，按照下表配置模型。在添加模型页面，参考下表配置。 
   图4配置模型示例   
   ![](https://support.huaweicloud.com/access-tools-maas/figure/zh-cn_image_0000002764272248.png "点击放大")
   
   表2模型配置 
   | 参数         | 说明                                                                                                                                                                                                                                                                                                             | 示例                    |
   |:---|:---|:---|
   | 模型ID     | 必填。 从[模型列表](https://support.huaweicloud.com/model-list-maas/model_list_0001.html)中的"模型参数"中获取。                                                                                                                                                                   | deepseek-v4.1-flash |
   | 上下文窗口    | 必填。 模型一次可处理的上下文容量，单位为Token。 可智能配置，配置为模型支持的上限。可从[模型列表](https://support.huaweicloud.com/model-list-maas/model_list_0001.html)中的"长度限制"中查看模型支持的上限。 **请勿超过模型的实际上下文限制。** | 1,000,000              |
   | 最大输出Token | 必填。 单次模型请求允许生成的最大Token数，单位为Token。 可智能配置，配置为模型支持的上限。可从[模型列表](https://support.huaweicloud.com/model-list-maas/model_list_0001.html)中的"长度限制"中查看模型支持的上限。 **请勿超过模型的实际上下文限制。** | 384,000               |
   | 高级配置      | 选填。可设置输入类型、模型能力、推理等级等。                                                                                                                                                                                                                                                                                         | -                     |
      
   
   
5. 单击"保存"后，单击模型操作栏的"测试模型"，连接成功表示模型添加成功。 
   图5测试模型   
   ![](https://support.huaweicloud.com/access-tools-maas/figure/zh-cn_image_0000002793474865.png "点击放大")
   ![](https://support.huaweicloud.com/access-tools-maas/figure/zh-cn_image_0000002770975780.png "点击放大")
   
   
 
#### 步骤三：使用ZCode
1. 在ZCode主页面左侧导航栏，选择"新建任务"，进入对话框，在对话框下方选择[步骤二：接入MaaS模型API]配置的模型，如下图所示：
   
   图6选择模型   
   ![](https://support.huaweicloud.com/access-tools-maas/figure/zh-cn_image_0000002763997674.png "点击放大")
   
   
   
2. 在对话框进行对话，体验模型，如下图所示： 
   图7对话示例   
   ![](https://support.huaweicloud.com/access-tools-maas/figure/zh-cn_image_0000002764276378.png "点击放大")
   
   
   
 
#### 常见报错
表3常见报错排查 
| 报错                                                         | 原因                       | 解决方法                                                                                                 |
|:---|:---|:---|
| 404 Provider returned a business error.                     | Base URL路径包含多余后缀。       | 确保所填路径不要带"/chat/completions"或"/v1/messages"后缀。                                                       |
| 401 Invalid authorization header                           | API Key错误或不完整。          | 检查Key是否完整复制、有无空格。                                                                                   |
| 429 Too Many Requests                                      | 请求频率超出限制。                 | 降低调用频率，稍后重试。                                                                                         |
| 403 Invalid request because you do not have access to it. | 模型未在MaaS开通。             | 在MaaS控制台开通对应预置服务。                                                                                    |
| Cannot connect to API                                      | 地址不可达或端口错误。             | 检查防火墙、内网地址是否可访问。                                                                                     |
| Invalid model                                             | 模型ID拼写错误。              | 核对大小写、多余空格。从 [模型列表](https://support.huaweicloud.com/model-list-maas/model_list_0001.html)核对正确的模型参数值。 |
| Connect Timeout Error                                        | 网络不稳定或上下文过长导致推理耗时。     | 检查网络；适当缩短输入内容。                                                                                      |
| 400 Bad request                                              | 配置的上下文窗口或最大输出Token超出模型上限。 | 根据[模型列表](https://support.huaweicloud.com/model-list-maas/model_list_0001.html)中的"长度限制"配置参数。           |