API 开发指南-大模型服务平台百炼(Model Studio)-阿里云帮助中心

本文介绍如何使用 AgentScope-AI 从零开始开发、上传和部署高代码应用的 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。