# 高代码应用创建部署指南
> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。
方舟高代码应用基于 veFaaS 函数服务等多个云产品，提供了便捷的在线部署流程和生产级的运行环境。本文将介绍如何完成火山方舟高代码应用的在线创建、部署、体验和修改全流程。
> **说明**
>
> 关于高代码应用的介绍请参考[高代码应用简介](/docs/high-code-app-overview)。如无法满足需求，您也可以选择使用 [高代码应用 SDK](https://github.com/volcengine/ai-app-lab/tree/main/arkitect) 在本地或其他环境进行开发。
> **注意**
>
> 高代码应用功能已对个人用户开放使用。如需使用，请 [完成实名认证](https://console.volcengine.com/user/authentication/detail/)。
## 一、创建高代码应用
登录火山方舟控制台，打开 [创建高代码应用](https://ark.volcengine.com/region:cn-beijing/assistant/edit?botType=ProCode&tab=Edit) 页面。
### 1.1 权限获取
* 进入高代码应用创建页时，您需具备高代码应用所需权限，将进行 IAM 权限校验。
* 高代码在线部署依赖 veFaaS 函数服务，需要授权 IAM 角色 `ServerlessApplicationRole`。
* 首次创建 IAM 角色需由主账号操作，如您登录的为子账号，可先点击**立即开通**，并根据提示点击**复制信息**并发送给主账号管理员，由主账号管理员创建角色并对子账号授权。
* 如您登录的为主账号，且已完成企业认证，
* 您可直接点击**立即开通**，进行 ServerlessApplicationRole 授权。
* 您也可请前往 [访问控制- 角色管理](https://console.volcengine.com/iam/identitymanage/role) 模块，进行空白角色服务新建，并在后续应用创建时，需根据提示添加权限。具体操作如下：
1. 点击**新建角色**。
2. 选择信任身份类型为「**服务**」，选择服务为「**函数服务**」，点击下一步。
3. 角色名填写：**ServerlessApplicationRole**，其余均不填，点击下一步。
4. 不选择策略，点击跳过，完成角色授权。
5. 后续在高代码应用创建时，根据提示按需配置策略：CloudMonitorReadOnlyAccess，TLSFullAccess，VPCFullAccess，VeFaaSFullAccess，STSAssumeRoleAccess，APIGFullAccess
* 完成授权后，将提示 `IAM 角色已授权`。
### 1.2 云产品服务开通
* 高代码应用在线部署依赖函数服务等多个云产品提供的服务，需要开通相关云产品。
* 若存在未开通产品，可通过页面上的**立即开通**，在阅读相关协议文档后批量开通相关云产品。
* 若提示“已开通所有云服务”则代表已完成开通。
### 1.3 创建高代码应用
填写应用名称等基础信息后，点击页面右上角“发布”按钮。
保存后即可通过**创建新函数**去部署高代码应用相关联的函数服务。
## 二、部署高代码应用
选择应用原型为“示例”。然后完成“创建函数应用”页面的配置，进行高代码应用函数服务的创建部署。
### 2.1 所需权限及产品开通
* 若在创建高代码应用时完成了权限获取和云产品开通，应当已具备所需权限和服务。
* 若 IAM 角色未授权或关联云服务未开通，请联系管理员进行授权或开通，可参考 [1.1 权限获取](/docs/high-code-app-creation-and-deployment-guide#afb4b2a6)。
### 2.2 选择推理接入点和 API Key
* 选择推理接入点，您可选择调用模型所需的推理接入点。详情可参见[获取 Endpoint ID（创建自定义推理接入点）](https://ark.volcengine.com/region:cn-beijing/docs/create-standard-inference-endpoint)。
* 选择 API Key，参见 [管理 API Key](/docs/manage-api-keys)。
### 2.3 填写函数名称
填写函数名称等基础信息。
### 2.4 配置日志服务-Trace（可选）
启用 Trace 日志服务后，系统将自动采集您请求的 input 和 output 及各阶段耗时信息，并记录在您的日志服务中，便于后续运维和排查。
> **注意**
>
> 启用 Trace 日志服务将可能产生额外费用，详见 [日志服务计费说明](https://docs.volcengine.com/docs/TorchLogService/Billingoverview-24)。
选择启用“日志服务-Trace”后，需要填写 API 访问密钥（AK/SK），可参考 [获取 AK/SK](https://console.volcengine.com/iam/keymanage)。
### 2.5 选择触发器
为了在调用时触发执行函数，需要在创建函数时关联触发器，现为您提供以下类型触发器。
|触发器类型 |目标群体 |创建流程 |调用流程 |
| --- | --- | --- | --- |
|方舟触发器（推荐使用） |默认提供，面向无特殊要求的大部分群体。 |创建高代码应用时选用方舟触发器，即可将函数服务关联到指定的高代码应用 ID。 |[获取方舟长效/短效 API key](/docs/base-url-and-authentication)，调用时通过方舟统一域名+BotID，使用 API key 鉴权。 |
|APIG 触发器-API 网关服务 |有独立部署网关需求 |已有 APIG：选择关联的 APIG。确认部署应用后将创建关联的 APIG 触发器。 |获取有效期 7 天的 jwt token，通过 APIG 调用，使用 [JWT token 鉴权](https://docs.volcengine.com/docs/APIGateway/JWTauthenticationandauthorization)。 | \
| |对信息传输安全性要求高，需要通过 VPC 保障数据安全。 |无 APIG 但有 VPC：跳转到 [APIG 控制台](https://console.volcengine.com/veapig)，创建好 APIG 后再关联。 | | \
| |对 APIG、VPC 了解深入，已有相关服务配套设施。 |无 VPC：跳转到 APIG 控制台，创建好 VPC 和 APIG 后再关联。 | |
### 2.6 确认部署
* 完成以上内容的填写后，点击确定进行部署。
* 部署需耗时约数分钟，请耐心等候。页面上将展示部署日志，若部署失败可根据日志信息定位原因。
* 部署成功后，可通过页面右上角按钮跳转到函数代码页编辑代码，或返回体验应用。
## 三、修改和体验高代码应用
完成部署后，您可根据业务需求对函数代码进行修改、更新、发布。
### 3.1 体验高代码应用和 Trace 追踪
等待应用完成部署，函数完成发布后，您就可以在高代码应用页面上和应用交互进行体验了。
在体验中得到的回答，可以点击右侧的“调试按钮”，获取调试信息。
您也可以参考下文修改优化高代码应用，让应用的表现更符合您的预期。
### 3.2 修改高代码应用
在高代码应用编辑页，点击“更新代码”进入函数代码管理页修改代码。
#### 方案一：在线编辑
* 您可在线进行代码修改，按照您的配置调整各插件参数，以进行效果和性能优化或实现业务逻辑。详见 SDK 说明文档
* 完成编辑后，点击保存按钮保存代码，保存完成后可进行函数发布。
#### 方案二：下载代码包编辑
##### 代码包下载
您可在函数代码页下载最新版本服务对应的代码包。
##### 修改代码
您可在本地 IDE 进行代码修改，按照您的配置调整插件参数，以进行效果和性能优化或实现业务逻辑。
详见[SDK 常见使用示例](/docs/sdk-common-examples)。
##### 代码包上传和保存
将本地代码包打包为 zip 文件后，上传更新函数代码。
如线上预览耗时较久，可能是代码包较大。建议在本地预览后，上传到函数服务进行发布。
#### 方案三：使用命令行工具编辑
可以联系我们获取 vefaas 命令行工具使用说明文档使用命令行工具，结合本地 IDE 进行代码编辑和发布等操作。
#### 函数发布
* 完成代码修改、上传、保存后，可根据需求进行全量发布/灰度发布，并配置函数版本。
建议使用灰度发布，防止变更失误影响线上服务。
* 灰度发布可配置比例
可在函数详情-发布管理找到灰度发布的版本，并调整灰度比例直至全量发布。
完成发布后，可点击对话测试返回。
### 3.3 调用和鉴权
* 方舟触发器：如果您配置了方舟触发器，可通过 Bot API 接口调用，使用 API key 鉴权。接口文档请参见[应用(bot) API](/docs/bot-api)。
* APIG 触发器：如果您配置了 APIG 触发器，可通过您配置的 APIG 访问地址进行调用。调用时需使用 [JWT token 鉴权](https://docs.volcengine.com/docs/APIGateway/JWTauthenticationandauthorization)。
## 四、添加 MCP 服务 (可选)
当前高代码应用已支持添加 MCP 服务，以下为具体操作指南：
### 4.1 创建应用并选择函数模板
根据步骤一的指引创建高代码应用，并点击**创建新函数**，在随后弹出的原型应用选择弹窗中，选择**示例-大模型 MCP 应用**，点击确认
### 4.2 配置函数及 MCP 服务
* 函数创建的基础配置请参照“步骤二”，例如权限及产品开通、推理接入点和 API Key、触发器选择、日志服务-Trace 等。
* 下面为您详细介绍如何添加 MCP 服务：
点击**添加更多 MCP 服务**，随后的弹窗已为您列出 [火山引擎大模型生态广场](https://www.volcengine.com/mcp-marketplace) 中的 MCP 服务，并支持添加自定义 MCP 服务。
* 根据业务需求选择所需的 MCP 服务。前往 [火山引擎大模型生态广场](https://www.volcengine.com/mcp-marketplace) 生成专属的 JSON 配置信息。如需填写相关环境变量参数，可根据**详情**中的 Readme 进行获取。（注：Remote MCP 添加较为便捷，但生成的 URL 存在 48 小时有效期，如需长期使用建议选择 Local MCP 或云部署 MCP 版本）
* 将生成的配置信息粘贴至 MCP 服务设置的 config.json 中，点击**确认并更新**。完成其他函数配置后，点击**确定**进行部署函数。
* 等待函数部署成功后，即可进行对话体验，并调用相应的 MCP 服务
### 4.3 二次编辑 MCP 服务
* 您可对 MCP 服务进行二次编辑，点击需要编辑的 MCP 服务或**添加更多 MCP 服务**按钮，操作流程同 4.2
* 完成编辑后，点击**确认并更新**，等待函数更新完成后，即可再次进行对话测试
## 附：MCP Tool 的接入与配置
由于不同 MCP Tool 对 Python 版本及工具版本的依赖存在差异，且火山 MCP Hub 生态持续迭代，方舟高代码模板无法预先安装所有 MCP 工具及其依赖。因此，当用户需在模板中调用特定工具时，需在高代码对应的 FaaS 函数中手动完成依赖安装与配置更新。
### **前置条件**
接入的 MCP Tool 需满足以下条件：
1. 支持通过启动命令参数`-t` 定义 MCP Server 的连接方式；
2. 支持通过环境变量 `PORT` 定义 MCP Server 的部署端口；
3. 该 MCP Server 的依赖与现有模板中 `requirements.txt` 的工具版本无冲突。
### **操作步骤**
#### **若满足前置条件（以 `mcp_server_vefaas_sandbox` 为例）**
1. 进入函数代码界面，下载完整代码包。
2. 在 `requirements.txt` 中添加该工具依赖。
```Plaintext
# ...其他requirement
mcp-server-vefaas-sandbox @ git+https://github.com/volcengine/mcp-server#subdirectory=server/mcp_server_vefaas_sandbox
```
3. 更新 `mcp_servers_connection.json`。
在 `available_mcp_servers` 对象中新增配置项`"mcp-server-vefaas-sandbox"`，内容如下：
```json
"mcp-server-vefaas-sandbox": {
"transport": {
"command": "-t"
},
"port": {
"env": "8000"
}
}
```
4. 压缩代码包并上传至 FaaS，完成依赖安装后发布。
#### **若不满足前置条件（以 `mcp_server_rds_mysql` 为例）**
若 MCP Tool 不满足前置条件（如 `mcp_server_rds_mysql` 通过环境变量 `MCP_SERVER_PORT` 定义端口，且依赖 `mcp[cli]>=1.10.0` 与现有环境冲突），需先修改 MCP Server 实现，参考方式如下：
1. 将火山 [MCP Hub 代码库](https://github.com/volcengine/mcp-server) fork 至个人仓库；
2. 修改 `server/mcp_server_rds_mysql` 下的工具实现，使其满足前置条件：
* 调整部署端口读取方式（适配 `PORT` 环境变量）：
```python
mcp_server = FastMCP("rds_mysql_mcp_server", port=int(os.getenv("PORT", "8000")))
```
* 更新依赖工具的版本，并确保版本变更不会影响工具的使用效果。若无法直接修改版本，请根据依赖冲突原因，调整高代码模板的 requirements.txt 以解决冲突。
```Plaintext
[project]
name = "mcp-server-rds-mysql"
version = "0.1.0"
description = "MCP server for RDS MySQL"
readme = "README.md"
requires-python = ">=3.10"
dependencies = [
"mcp[cli]>=1.9.2", # 调整版本以解决冲突
"volcengine-python-sdk>=3.0.1",
"aiohttp>=3.11.14",
"deprecated>=1.2.18",
]
[project.scripts]
mcp-server-rds-mysql = "mcp_server_rds_mysql.server:main"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
```
3. 在模板的 `requirements.txt` 中添加个人仓库的依赖：
```Plaintext
# ...其他requirement
mcp-server-vefaas-sandbox @ git+https://github.com/{你的github id}/mcp-server#subdirectory=server/mcp_server_vefaas_sandbox
```
4. 后续请参考前文满足条件后的操作。
### **常见问题**
#### 发布后对话无内容或无法唤起工具
这种情况大多数是因为 mcp server 连接失败。可以前往 faas 实例 -> 资源管理，进入实例 webshell 中排查连接问题。可以参考下面的常用手段。
##### Step 1：查看 MCP Server 连接信息
执行以下命令查看所有 MCP Server 的连接配置：
```bash
cat /tmp/mcp_config/merged_mcp_servers_config.json
```
你可能会看到类似的信息：
```json
{
"mcpServers": {
"mcp-server-rds-mysql": {
"url": "http://localhost:7001/sse"
},
}
}
```
请依次对这些 url 执行 curl 测试，确认 MCP Server 是否可访问。
##### Step 2：检查无法访问的 MCP Server
如果某个 url 无法访问，则说明对应的 MCP Server **启动失败**。
可以通过查看该 MCP Server 的启动日志来确认失败原因：
```bash
cat /tmp/{mcp_server_name}.err.out
```
例如：
```bash
cat /tmp/mcp-server-rds-mysql.err.out
```
## 相关参考
[MaaS 高代码链路监控](https://docs.volcengine.com/docs/ObservabilityPlatform/MaaShigh-codelinkmonitoring)