使用高代码应用将Python项目部署为API服务-大模型服务平台百炼-阿里云-大模型服务平台百炼(Model Studio)-阿里云帮助中心

阿里云百炼平台的高代码应用功能，允许开发者基于完整的 Python 项目结构部署 AI 后端服务。

与“低代码/无代码”拖拽式开发不同，高代码应用允许您使用代码编程的方式构建复杂 AI 服务。
使用单条命令即可快速将 Python 项目部署为公网可访问云上后端 API 服务。
支持自动化运维、可观测、日志服务、API网关等企业级能力。

快速开始

前往阿里云百炼-应用观测页面，授权开通应用观测功能。
前往阿里云百炼-应用管理，单击创建应用，选择高代码应用，再选择控制台创建。

创建时需按照页面引导授权函数计算FC、API 网关两个服务的相关角色和权限。如遇权限不足，请联系您的账号管理员或 IT 管理员获取相关授权。
在应用部署页面选择任意的模板，部署资源、规格方案等参数保持默认，不进行修改，立即部署模板应用。

部署成功后，将开始收取少量函数、网关、存储、日志等费用。
等待几分钟完成应用函数的部署和发布。等待过程中可实时查看函数构建和部署日志。

待部署完成后，配置阿里云百炼的 API-Key后，即可使用右侧的文本对话体验模式，进行体验和调试。 API-Key 获取方式请参考：获取 API Key。

也可使用API 测试模式在控制台手动调试定制的 API 接口：

应用模板	支持的接口
基础对话 Agent	健康检查接口：`GET /health`，用于告知应用函数，服务已成功启动。预期响应：`"OK"`。联调接口：`/process`，用于与大模型通信。模板的请求样例： `curl -X POST https://xxxxxxxx/process \ -H "Content-Type: application/json" \ -d '{ "input": [ { "role": "user", "content": [ { "type": "text", "text": "你好，世界！" } ] } ], "session_id": "test-session", "user_id": "test-user" }'` 预期输出为流式输出内容，请拷贝到本地解析。
工具调用 Agent，内置天气查询 MCP。 `{ "type": "text", "text": "今天杭州天气怎么样?"}'`
深度研究 Agent，内置互联网搜索 MCP。 `{ "type": "text", "text": "帮我分析下近期的金价走势" }'`

应用管理

在高代码应用的详情页面中单击重新部署按钮，可以更新应用部署相关的所有设置，包含上传新的代码包，调整应用性能（修改资源规格、资源实例数和并发度）、修改部署地域。

更新配置或重启服务后，应用都将重新构建和部署，应用网关也需要重新关联。

应用网关

当应用测试稳定、性能满足预期后，需要在生产环境部署应用，建议开启应用网关功能，通过自定义域名和网关路由访问云上服务。

在高代码应用的详情页面中，单击应用网关，根据控制台引导，根据需求创建阿里云的云原生 API 网关。（将会产生少量的使用费用，具体价格表请参考：云原生 API 网关计费概述）

应用部署地域应与应用网关所在地域相同。
新的 API 路由和 Token 鉴权生效后也能正常访问高代码应用。
在生产环境中使用应用：推荐打开测试域名的“禁止公网访问”开关，测试用触发器将不再能够通过公网访问。

调用示例：

curl -i -X POST "http://{change-to-your-domain}/{change-to-your-agentCode}/process" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 替换为应用网关鉴权token" \
  -d '{
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "帮我说一下什么是四书五经" }
        ]
      }
    ],
    "session_id": "xxxxxx",
    "user_id": "xxxxx"
  }'

API 开发指南

环境准备

Python 开发环境要求python >= 3.10。
为了能够将 Python 代码上传并部署到阿里云百炼，安装 AgentScope-AI 的相关依赖，用于向阿里云百炼上传代码包：
```
pip install agentscope-runtime==1.0.0
pip install "agentscope-runtime[deployment]==1.0.0"
```

开发规范

Python 后端程序必须提供GET /health接口。若该接口无法调用，百炼将判定程序启动失败。
Python 后端程序的入口文件必须为main.py。
对话接口路径，默认使用/process，协议可参考 Agent API 协议规范。
开发参考代码包：mcp_server_with_chat.zip。

应用观测植入

通过使用 AgentScope-runtime 包提供的@trace装饰器，可以自动上报日志，统计耗时。

针对大模型调用函数的装饰器示例：

from agentscope_runtime.engine.tracing import trace, TraceType


@trace(trace_type=TraceType.LLM, trace_name="llm_func")
def llm_func(): 
  pass

示例输出：

{"time": "2025-08-13 11:23:41.808", "step": "llm_func_start", "model": "", "user_id": "", "code": "", "message": "", "task_id": "", "request_id": "", "context": {}, "interval": {"type": "llm_func_start", "cost": 0}, "ds_service_id": "test_id", "ds_service_name": "test_name"}
{"time": "2025-08-13 11:23:41.808", "step": "llm_func_end", "model": "", "user_id": "", "code": "", "message": "", "task_id": "", "request_id": "", "context": {}, "interval": {"type": "llm_func_end", "cost": "0.000"}, "ds_service_id": "test_id", "ds_service_name": "test_name"}

如需自定义日志上报、支持流式输出函数、设置日志公共属性等功能，请参考： AgentScope-runtime 的 Tracing 模块。

如果从控制台上创建应用时，需要打开应用观测开关。

如果使用AgentScope-AI上传构建好的.whl 软件包，需要添加--telemetry enable来开启应用观测功能。

runtime-fc-deploy --deploy-name 我的第一个高代码应用  --whl-path <PATH_TO_YOUR_NEW_WHL_FILE> --telemetry enable

应用运行后，可在阿里云百炼-应用观测页面查看收集到的相关信息。

应用上传

获取并配置以下环境变量（以 Linux 系统为例）

获取阿里云的 AccessKey（AK 和 SK），用于上传软件包时的鉴权。
（可选）获取阿里云百炼的 Workspace ID，以llm-开头，用于指定存储高代码应用的百炼业务空间，不设置将使用默认业务空间。

将以上获取到的内容配置为环境变量：

export ALIBABA_CLOUD_ACCESS_KEY_ID=LTAI************            #替换为阿里云AccessKey(AK)
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=****************        #替换为阿里云SecretKey(SK)
export MODELSTUDIO_WORKSPACE_ID=llm-****************           #可选，替换为百炼的业务空间ID，该空间将部署高代码应用，不设置将使用默认业务空间

使用AgentScope-AI上传构建好的.whl 软件包，并自动部署到阿里云百炼。

--telemetry enable用于打开可观测能力，并需要结合 AgentScope 的 Tracing 模块进行应用开发。
```
runtime-fc-deploy --deploy-name 我的第一个高代码应用  --whl-path <PATH_TO_YOUR_NEW_WHL_FILE> --telemetry enable
```
部署成功后会打印出应用名、百炼业务空间、访问应用的控制台链接、应用 ID。
前往阿里云百炼-应用管理控制台，等待应用发布。应用发布后将会根据部署时长，产生较少的费用。（<0.1元/小时）

应用测试

建议前往阿里云百炼-应用管理，在应用详情页测试并查看构建、部署、调用日志。

应用更新

当高代码应用需要更新时，可以使用 AgentScope-AI 的更新命令重新上传.whl 软件包。软件包上传成功后，高代码应用将自动更新并重新部署运行。

前往阿里云百炼-应用管理，复制应用 ID。
在本地使用以下命令，上传更新的本地.whl 软件包。

应用更新后，应用将重新构建、部署。
```
runtime-fc-deploy --update <HIGH_CODE_APP_ID> --whl-path <PATH_TO_YOUR_NEW_WHL_FILE>
```
更新成功后显示：

常见问题

RAM 账号最小化授权

RAM 账号需要最小化赋权使用高代码应用时，可以基于以下规则创建高代码应用的自定义权限策略。

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "sfm:ApplyTempStorageLease",
        "fc:ListTriggers",
        "fc:GetFunction",
        "fc:GetFunctionCode",
        "fc:UpdateFunction",
        "log:GetProject",
        "log:GetLogStore",
        "log:GetIndex"
      ],
      "Resource": "*"
    }
  ]
}

上传失败了如何排查？

请检查阿里云的 AK/SK 与阿里云百炼的 Workspace ID 是否属于同一个账号。
请检查各项前置条件均已满足或开通。

请尝试使用一个干净的python >= 3.10的环境，比如使用 Python 的 venv 命令创建一个干净的虚拟环境：

创建环境：
```
python --version
python -m venv venv
```

加载环境

# Linux / macOS
source venv/bin/activate

# Windows (CMD)
venv\Scripts\activate.bat

# Windows (PowerShell)
venv\Scripts\Activate.ps1

上传时代码运行报错 “RAM user is not assigned to any workspace in Bailian”，请联系阿里云主账号的拥有者进行以下操作：
1. 由阿里云主账号为阿里云子账号（RAM用户）在 RAM 控制台添加 AliyunBailianDataFullAccess 权限。
2. 为子账号（RAM用户）在百炼账号管理页面添加特定业务空间的智能体-操作权限。

控制台一直显示部署中（超过 5 分钟）或部署失败可能是什么原因？

Python 后端程序的GET /health 接口无法调用，导致百炼认为程序启动失败。
Python 后端程序的入口文件必须为main.py。
可以前往高代码应用详情页中，查看具体的运行日志。

API 调用报错 `Invalid API-key Provided`?

说明高代码应用的环境变量中未正确配置百炼的 API-Key，获取方式请参考：获取 API Key。