O EMR AI Assistant é um service de IA conversacional. Você pode usar linguagem natural para enviar solicitações por meio de uma API e realizar automaticamente diagnósticos de SQL lento e verificações de integridade em suas instâncias Serverless StarRocks, recebendo sugestões de otimização. Este tópico descreve como chamar a API do EMR AI Assistant usando o SDK do Python.
Recursos
O EMR AI Assistant oferece os seguintes recursos principais:
Diagnóstico de SQL lento: Identifica as consultas com maior tempo de execução, localiza gargalos de desempenho e fornece sugestões de otimização.
Verificação de integridade: Realiza uma verificação abrangente na sua instância e gera uma pontuação de integridade, uma lista de problemas e sugestões de melhoria.
É possível enviar solicitações em linguagem natural sem precisar construir manualmente chamadas de API ou configurar parâmetros de tarefa.
Etapa 1: Instale as dependências
Execute o comando a seguir para instalar o Alibaba Cloud OpenAPI SDK:
pip install alibabacloud_tea_openapi alibabacloud_tea_util
Etapa 2: Configure seu AccessKey
Configure seu AccessKey da Alibaba Cloud usando variáveis de ambiente:
export ALIBABA_CLOUD_ACCESS_KEY_ID=<your_access_key_id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your_access_key_secret>
O EMR AI Assistant usa a identidade desta conta para acessar dados e só pode acessar instâncias pertencentes a ela. Certifique-se de que o service EMR AI Assistant esteja ativado para esta conta e que ela tenha permissão para acessar a instância de destino.
Não codifique seu AccessKey diretamente no código. Recomendamos passar as credenciais usando variáveis de ambiente para maior segurança.
Etapa 3: Escreva o código do cliente
Substitua ENDPOINT no código a seguir pelo endpoint da região da sua instância.
Regiões suportadas
|
Região |
ID da região |
Endpoint |
|
China (Hangzhou) |
cn-hangzhou |
|
|
China (Shanghai) |
cn-shanghai |
|
|
China (Qingdao) |
cn-qingdao |
|
|
China (Beijing) |
cn-beijing |
|
|
China (Hohhot) |
cn-huhehaote |
|
|
China (Ulanqab) |
cn-wulanchabu |
|
|
China (Shenzhen) |
cn-shenzhen |
|
|
China (Chengdu) |
cn-chengdu |
|
|
Singapore |
ap-southeast-1 |
|
Código completo do cliente
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: The endpoint for your instance's region.
# For a complete list, see the table above.
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:
"""Sends a question to the assistant and streams the response. Returns a session ID for follow-up questions."""
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]: Marks the end of the response stream.
continue
msg = json.loads(data)
if msg.get("type") == "run_started":
session_id = msg.get("sessionId") # Capture the session ID.
elif msg.get("type") == "text":
sys.stdout.write(msg.get("text", "")) # Stream output in real time.
sys.stdout.flush()
except Exception as e:
print(f"\n[API call failed] {e}", file=sys.stderr)
print("Check that your AccessKey is correct, the EMR AI Assistant service is activated, "
"and the endpoint matches your instance's region.", file=sys.stderr)
return session_id
print()
return session_id
Exemplos de uso
Forneça o ID da instância (começando com c-) e sua região na sua pergunta. O assistente usa essas informações para localizar automaticamente a instância de destino.
Diagnóstico de SQL lento
client = create_client()
chat(client,
"My Serverless StarRocks instance c-xxxxxxxx (cn-hangzhou) has been slow recently. "
"Help me diagnose the top slow SQL queries, identify bottlenecks, and provide optimization suggestions.")
O assistente identifica automaticamente as consultas com maior tempo de execução, localiza padrões de SQL que consomem muitos recursos, analisa tendências e fornece sugestões de otimização para consultas lentas específicas.
Verificação de integridade
client = create_client()
chat(client,
"Perform a health check on Serverless StarRocks instance c-xxxxxxxx (cn-hangzhou) and generate a report.")
O assistente realiza uma verificação abrangente na instância e gera uma pontuação de integridade, uma lista de anomalias e sugestões de melhoria.
Saída de exemplo
Os exemplos a seguir mostram a saída real. As informações da instância foram ocultadas para preservar a privacidade.
Saída do diagnóstico de SQL lento
O assistente localiza automaticamente a instância, recupera as consultas que consumiram mais recursos recentemente e fornece um diagnóstico no nível de perfil:
Instance: c-xxxxxxxx (StarRocks 3.2.4, Running)
Most CPU-intensive query in the last hour: An information_schema metadata query
Diagnosis: Total time 102 ms / CPU 43.5 ms / Peak memory 3.21 MB / Wait ratio 80.88%
Bottleneck operators: SCHEMA_SCAN(node 7) 9.26 ms, SCHEMA_SCAN(node 0) 8.16 ms, HASH_JOIN(node 5) 1.28 MB
Conclusion: This query has a low workload and does not require optimization. If it occurs frequently, we recommend that you cache metadata on the client or use a connection pool.
Saída da verificação de integridade
Instance: c-xxxxxxxx (StarRocks 3.2.4, onBareMetal / lakehouse, Running)
Health score: 100/100
Key metrics: Last 24h: Critical 0 / Warning 0 / Info 0. The overall stability is excellent.
Anomalies: None
Improvement suggestions: Evaluate a version upgrade, enable automatic minor version upgrades, set up regular health checks and alerts, and assess resource specifications based on business growth.
Conversas de múltiplas rodadas
A função chat() retorna um ID de sessão. Você pode passar esse ID nas chamadas subsequentes para continuar a conversa no mesmo contexto. Por exemplo, se você não especificar uma instância na primeira solicitação, o assistente perguntará qual é, e você poderá fornecer a informação na próxima rodada:
client = create_client()
# Turn 1: No instance is specified, so the assistant asks which instance to diagnose.
sid = chat(client, "Help me diagnose slow SQL queries in StarRocks.")
# Turn 2: Pass the session ID back and provide the instance information.
chat(client, "The instance is c-xxxxxxxx, in cn-hangzhou", session_id=sid)
Melhores práticas
Especifique a tarefa e o alvo
O assistente decide se deve chamar a API de diagnóstico com base no seu prompt. Inclua tanto uma ação quanto um alvo:
Ação: Use verbos claros, como verificar, diagnosticar, identificar ou otimizar.
Alvo: O ID da instância (que começa com
c-) e sua região.
Se você fornecer ambos, o assistente acionará um diagnóstico. Se algum estiver ausente, a solicitação recorrerá a perguntas e respostas baseadas em conhecimento, e nenhum dado da instância será recuperado.
|
Tipo |
Prompt de exemplo |
Comportamento do assistente |
|
Diagnóstico de instância |
"Realize uma verificação de integridade na instância |
Conecta-se à instância e recupera dados reais. |
|
Perguntas e respostas baseadas em conhecimento |
"Qual é a diferença entre a arquitetura shared-data e a arquitetura shared-nothing no StarRocks?" |
Responde com base no conhecimento do product sem chamar a API de diagnóstico. |
Entenda a resposta
Os dados coletados e os resultados retornados variam conforme sua solicitação:
|
Solicitação |
Dados coletados |
Saída |
|
Verificação de integridade |
Eventos de integridade e métricas de monitoramento, como CPU, memória, JVM, I/O de disco e desempenho de consultas. |
Uma pontuação de integridade, uma lista de problemas e sugestões de melhoria. |
|
Diagnóstico de SQL lento |
Log de auditoria do FE e dados agregados de padrões de SQL. |
Principais consultas lentas, identificação de gargalos e sugestões de otimização. |
Interprete corretamente resultados vazios
Se uma instância tiver um baixo volume de consultas, um diagnóstico de SQL lento pode retornar "nenhuma consulta lenta significativa encontrada", e uma verificação de integridade pode relatar "baixa carga de trabalho e recursos suficientes". Isso significa que a instância está saudável e não indica uma falha na chamada da API.
Avançado: Roteie diretamente para o agente StarRocks
Por padrão, o EMR AI Assistant primeiro identifica sua intenção e depois encaminha a solicitação para o subassistente apropriado. Se seu fluxo de trabalho envolver apenas Serverless StarRocks, você pode especificar ServerlessStarrocksV3Agent para o parâmetro model no corpo da solicitação. Isso ignora o processo de roteamento de intenção, melhorando a estabilidade do diagnóstico:
# Add the model field to the existing body.
body = {
"stream": True,
"model": "ServerlessStarrocksV3Agent", # Directly route the request to the StarRocks agent.
"messages": [{"role": "user",
"content": "Perform a health check on instance c-xxxxxxxx (cn-wulanchabu) and generate a report."}],
}
|
Parâmetro Model |
Descrição |
|
Não especificado ou definido como |
O roteamento de intenção padrão é usado. Adequado para cenários em que é difícil determinar o agente de destino. |
|
|
A solicitação é enviada diretamente ao agente StarRocks. Ideal para fluxos de trabalho dedicados que envolvem apenas diagnóstico ou verificações de integridade do StarRocks. |