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診斷或巡檢的固定情境。 |