Todos os produtos
Search
Central de documentação

E-MapReduce:Call the EMR AI Assistant API

Última atualização: Aug 20, 2026

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>
Importante
  • 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

emrassistant.cn-hangzhou.aliyuncs.com

China (Shanghai)

cn-shanghai

emrassistant.cn-shanghai.aliyuncs.com

China (Qingdao)

cn-qingdao

emrassistant.cn-qingdao.aliyuncs.com

China (Beijing)

cn-beijing

emrassistant.cn-beijing.aliyuncs.com

China (Hohhot)

cn-huhehaote

emrassistant.cn-huhehaote.aliyuncs.com

China (Ulanqab)

cn-wulanchabu

emrassistant.cn-wulanchabu.aliyuncs.com

China (Shenzhen)

cn-shenzhen

emrassistant.cn-shenzhen.aliyuncs.com

China (Chengdu)

cn-chengdu

emrassistant.cn-chengdu.aliyuncs.com

Singapore

ap-southeast-1

emrassistant.ap-southeast-1.aliyuncs.com

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 c-xxxxxxxx (cn-wulanchabu)."

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 emr-assistant

O roteamento de intenção padrão é usado. Adequado para cenários em que é difícil determinar o agente de destino.

ServerlessStarrocksV3Agent

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.