EMR AI助手是一款对话式智能服务，支持通过API以自然语言方式提交诉求，自动完成Serverless StarRocks实例的慢SQL诊断与健康巡检，并提供相应的优化建议。本文介绍如何通过Python SDK调用EMR AI助手API。
功能概览
EMR AI助手提供以下核心功能：
慢SQL诊断：识别耗时最长的查询，定位性能瓶颈，并提供优化建议。
健康巡检：对实例进行全面检测，输出健康评分、问题清单与改进建议。
您仅需以自然语言方式提交问题，无需手动拼装接口或配置任务参数。
步骤一：安装依赖
执行以下命令安装阿里云OpenAPI SDK：
pip install alibabacloud_tea_openapi alibabacloud_tea_util步骤二：配置AccessKey
通过环境变量配置阿里云账号的AccessKey：
export ALIBABA_CLOUD_ACCESS_KEY_ID=<您的AccessKey ID>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<您的AccessKey Secret>EMR AI助手将以该账号身份访问数据，仅能访问该账号下的实例。请确保账号已开通EMR AI助手服务，并具有目标实例的访问权限。
请勿将AccessKey硬编码至代码中，建议通过环境变量方式传入，以保障凭据安全。
步骤三：编写客户端代码
将以下代码中的ENDPOINT替换为实例所在地域对应的接入地址。
支持地域
地域 | Region ID | 接入地址（Endpoint） |
华东1（杭州） | cn-hangzhou |
|
华东2（上海） | cn-shanghai |
|
华北1（青岛） | cn-qingdao |
|
华北2（北京） | cn-beijing |
|
华北5（呼和浩特） | cn-huhehaote |
|
华北6（乌兰察布） | cn-wulanchabu |
|
华南1（深圳） | cn-shenzhen |
|
西南1（成都） | cn-chengdu |
|
新加坡 | ap-southeast-1 |
|
完整客户端代码
import json
import os
import sys
from alibabacloud_tea_openapi.client import Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_tea_util import models as util_models
# 接入地址 ENDPOINT：按您实例所在地域填写，完整列表请参见上方表格
ENDPOINT = "emrassistant.cn-hangzhou.aliyuncs.com"
def create_client() -> Client:
return Client(open_api_models.Config(
access_key_id=os.environ["ALIBABA_CLOUD_ACCESS_KEY_ID"],
access_key_secret=os.environ["ALIBABA_CLOUD_ACCESS_KEY_SECRET"],
endpoint=ENDPOINT,
))
_PARAMS = open_api_models.Params(
action="ChatCompletion", version="2025-07-23", protocol="HTTPS",
method="POST", pathname="/v1/chat/completions",
auth_type="AK", style="ROA", req_body_type="json", body_type="json",
)
def chat(client: Client, question: str, session_id: str = None) -> str:
"""向助手提问，实时打印回答。返回会话标识，用于继续追问。"""
body = {"stream": True, "messages": [{"role": "user", "content": question}]}
if session_id:
body["sessionId"] = session_id
request = open_api_models.OpenApiRequest(body=body)
runtime = util_models.RuntimeOptions(connect_timeout=10_000, read_timeout=300_000)
try:
for resp in client.call_sseapi(_PARAMS, request, runtime):
data = resp.event.data if resp.event else None
if not data or data == "[DONE]": # [DONE]：回复结束标记
continue
msg = json.loads(data)
if msg.get("type") == "run_started":
session_id = msg.get("sessionId") # 记下会话标识
elif msg.get("type") == "text":
sys.stdout.write(msg.get("text", "")) # 边收边打印
sys.stdout.flush()
except Exception as e:
print(f"\n[调用失败] {e}", file=sys.stderr)
print("请检查：AccessKey是否正确、账号是否已开通EMR AI助手、"
"Endpoint地域是否与实例所在地域一致。", file=sys.stderr)
return session_id
print()
return session_id使用示例
提问时请同时提供实例ID（以c-开头）及所在地域，助手将自动定位至目标实例。
慢SQL诊断
client = create_client()
chat(client,
"我的Serverless StarRocks实例c-xxxxxxxx（cn-hangzhou）最近查询很慢，"
"帮我诊断Top慢SQL，定位瓶颈并给出优化建议")助手将自动识别耗时最长的查询、定位高资源消耗的SQL模式、分析变化趋势，并针对具体慢查询提供优化建议。
健康巡检
client = create_client()
chat(client,
"对Serverless StarRocks实例c-xxxxxxxx（cn-hangzhou）做一次健康巡检，输出体检报告")助手将对实例进行全面检测，输出健康评分、异常项清单及改进建议。
实际效果示例
以下为实际运行效果展示（实例信息已脱敏）：
慢SQL诊断效果
助手自动定位实例、提取近期资源消耗最高的查询，并输出Profile级诊断结果：
实例：c-xxxxxxxx（StarRocks 3.2.4，运行中）
最近1小时最耗CPU的查询：一条information_schema元数据查询
诊断：总耗时102ms / CPU 43.5ms / 峰值内存3.21MB / 等待占比80.88%
瓶颈算子：SCHEMA_SCAN(node 7) 9.26ms、SCHEMA_SCAN(node 0) 8.16ms、HASH_JOIN(node 5) 1.28MB
结论：该查询负载很低、无需优化；如高频出现，建议客户端缓存元数据/复用连接池健康巡检效果
实例：c-xxxxxxxx（StarRocks 3.2.4，onBareMetal / lakehouse，运行中）
健康评分：100 / 100
关键指标：过去24h Critical 0 / Warning 0 / Info 0，整体稳定性优秀
异常项：无
改进建议：评估版本升级；启用自动小版本升级；建立定期健康检查与告警；按业务增长评估资源规格多轮对话
chat()函数将返回会话标识，将该标识传回即可在同一上下文中继续提问。例如首次未指定实例时，助手会进行追问，您可补充相关信息：
client = create_client()
# 第1轮：未指定实例，助手将追问"是哪个实例？"
sid = chat(client, "帮我诊断一下StarRocks的慢SQL")
# 第2轮：传回会话标识，补充实例信息
chat(client, "实例是c-xxxxxxxx，在cn-hangzhou", session_id=sid)最佳实践
明确诉求和对象
助手根据提问内容决定是否调用诊断接口，提问需同时包含动作和对象：
动作：使用明确动词，如巡检、诊断、定位、优化。
对象：实例ID（
c-开头）+ 所在地域。
同时提供两者即可触发真实诊断；若缺失任一项，将退化为知识问答，不会拉取实例数据。
类型 | 提问示例 | 助手行为 |
触发真实诊断 | “对实例 | 连接实例并拉取真实数据 |
仅返回知识问答 | “StarRocks存算分离和存算一体有什么区别” | 基于产品知识回答，不调用诊断接口 |
了解返回结果
不同诉求触发的数据采集范围和返回结果如下：
诉求 | 采集数据 | 返回结果 |
健康巡检 | 健康事件、CPU/内存/JVM/磁盘IO/查询性能等监控指标 | 健康评分、问题清单、改进建议 |
慢SQL诊断 | FE审计日志、SQL Pattern聚合数据 | Top慢查询、瓶颈定位、优化建议 |
正确理解空结果
如果实例查询量较少，慢SQL诊断可能返回“无明显慢查询”，健康巡检可能显示“负载较低、资源充裕”。这表示实例当前运行健康，并非API调用异常。
进阶：固定直达StarRocks助手
默认情况下，EMR AI助手会先识别您的意图，再分发至对应的子助手。若您仅使用Serverless StarRocks场景，可在请求body中将model指定为ServerlessStarrocksV3Agent，跳过意图路由环节，以提升诊断稳定性：
# 在原有body基础上新增model字段即可
body = {
"stream": True,
"model": "ServerlessStarrocksV3Agent", # 固定直达StarRocks助手，跳过意图路由
"messages": [{"role": "user",
"content": "对实例c-xxxxxxxx（cn-wulanchabu）做一次健康巡检，输出体检报告"}],
}model参数 | 说明 |
不传或传入 | 采用默认意图路由，适用于难以判断目标助手的场景。 |
| 直达StarRocks助手，适用于专门进行StarRocks诊断或巡检的固定场景。 |