AI Ask API
A AI Ask API pega uma pergunta em linguagem simples, pede ao provedor LLM configurado que preencha uma consulta tipada contra o schema vivo do cubo, passa essa consulta pelo mesmo conversor que a AI Query API tipada usa, e devolve o resultado executado + o MDX gerado + a requisição estruturada que o modelo emitiu.
É a camada de linguagem natural sentada em cima da superfície tipada
para agentes. Onde a API tipada assume que quem chama fala
AiQueryRequest, a ask API deixa uma pessoa dizer “mostra as vendas
por país no trimestre passado” e receber um cellset totalmente
executado, com a tradução do modelo visível ao lado.
Isso move a gaveta AI Query do workspace — o botão ⚡ na barra de ferramentas abre um painel de chat onde os usuários digitam perguntas e clicam em Editar no canvas para soltar o resultado na aba de consulta ativa.
Quando usar
A ask API é a superfície certa quando:
- Usuários finais vão digitar perguntas — a AI Query API tipada espera um agente que já conheça o schema do cubo; a ask API esconde esse passo atrás de um LLM.
- Você quer um round-trip por pergunta —
/ai/askfaz tradução + execução + moldagem do envelope numa única chamada, então o cliente não precisa encadear duas APIs. - Você está embutindo uma superfície tipo chat — o campo
multivoltas
historydeixa perguntas de acompanhamento se resolverem contra voltas anteriores.
Quando não usar:
- Agentes no servidor MCP — agentes preferem a superfície tipada porque já são bons em preencher campos estruturados a partir de um JSON Schema. A camada ask é para humanos.
- Criar cubos a partir de um warehouse de amostra — use a AI Inference API, feita para o fluxo de projeto.
Ativação
Duas propriedades + uma variável de ambiente por provedor. As duas podem ser definidas na JVM ou no arquivo de propriedades do deployment que o Spring lê.
# Anthropic Claudesaiku.ai.ask.provider = anthropic# env ANTHROPIC_API_KEY = sk-ant-...
# OpenAI — or any OpenAI-compatible host (vLLM, Ollama, Together, LiteLLM)saiku.ai.ask.provider = openai# env OPENAI_API_KEY = sk-...
# Azure OpenAI Service (saiku#1431). See BYOLLM below.saiku.ai.ask.provider = azure-openaisaiku.ai.ask.endpoint = https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=2024-02-15-previewsaiku.ai.ask.model = <deployment># env AZURE_OPENAI_API_KEY = <azure-key>
# Optional, all providerssaiku.ai.ask.model = claude-sonnet-4-6 | gpt-4o-mini | ...saiku.ai.ask.endpoint = https://my.openai-compatible.host/v1/chat/completionssaiku.ai.ask.apiKey = ... # explicit override of the env varsaiku.ai.ask.timeoutSeconds = 60 # or env SAIKU_AI_ASK_TIMEOUT_SECONDSPadrões por provedor:
| Provedor | Modelo padrão | Endpoint |
|---|---|---|
anthropic | claude-sonnet-4-6 | https://api.anthropic.com/v1/messages |
openai | gpt-4o-mini | https://api.openai.com/v1/chat/completions |
azure-openai | (sem padrão) | (sem padrão — recusa se construir sem uma URL de deployment explícita) |
Docker
docker run -d --name saiku \ -e ANTHROPIC_API_KEY=sk-ant-... \ -e JAVA_OPTS='-Dsaiku.ai.ask.provider=anthropic' \ ghcr.io/spiculedata/saiku:latestKubernetes
Use um Secret para a chave e um ConfigMap para o nome do provedor:
apiVersion: v1kind: Secretmetadata: name: saiku-aitype: OpaquestringData: ANTHROPIC_API_KEY: sk-ant-...---apiVersion: apps/v1kind: Deploymentmetadata: name: saikuspec: template: spec: containers: - name: saiku envFrom: - secretRef: name: saiku-ai env: - name: JAVA_OPTS value: -Dsaiku.ai.ask.provider=anthropicBYOLLM — traga o seu próprio modelo (saiku#1431)
Deployments enterprise muitas vezes não podem mandar prompts direto para a Anthropic ou a OpenAI — o LLM precisa rodar dentro da VPC do cliente ou atrás das compras que ele já aprovou. A camada ask cobre os três formatos de BYOLLM mais comuns sem assar dependências pesadas dentro do Saiku.
| Formato | Provedor | Formato do endpoint | Header de auth |
|---|---|---|---|
| Azure OpenAI Service | azure-openai | https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=<v> | api-key: <key> |
| Auto-hospedado / proxy compatível com OpenAI (vLLM, Ollama, LiteLLM, Together, Groq) | openai | qualquer URL que fale a Chat Completions API da OpenAI | Authorization: Bearer <key> |
| AWS Bedrock com LiteLLM na frente | openai | LiteLLM na frente do Bedrock (https://litellm.internal/v1/chat/completions) | Authorization: Bearer <litellm-key> |
O adaptador nativo azure-openai cuida das duas coisas específicas da
Azure (nome do deployment na URL e header api-key) para os operadores
não terem que rodar um proxy de tradução no caso mais comum.
Ativação do Azure OpenAI
-
Faça deploy de um modelo compatível com OpenAI no seu recurso Azure OpenAI. Anote o nome do recurso e o do deployment.
-
Pegue uma chave no portal da Azure → seu recurso → Keys and Endpoint.
-
Defina no launcher:
saiku.ai.ask.provider = azure-openaisaiku.ai.ask.endpoint = https://my-resource.openai.azure.com/openai/deployments/my-deployment/chat/completions?api-version=2024-02-15-previewsaiku.ai.ask.model = my-deployment# env AZURE_OPENAI_API_KEY = <azure-api-key> -
Suba o launcher. Uma linha INFO no início confirma a ligação:
INFO o.s.s.o.a.a.NlAskProviderFactory - AI ask provider: azure-openai (deployment/model=my-deployment, endpoint=https://…)
AWS Bedrock via LiteLLM
O padrão recomendado para Bedrock é rodar
LiteLLM como front compatível com OpenAI e
apontar o provedor openai que o Saiku já tem para o LiteLLM. O LiteLLM
cuida da assinatura SigV4 rio acima, então o Saiku não precisa do SDK da
AWS no classpath.
model_list: - model_name: claude-sonnet-3-5 litellm_params: model: bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0 aws_region_name: us-east-1
litellm_settings: drop_params: truelitellm --config litellm-config.yaml --port 4000E então, do lado do Saiku:
saiku.ai.ask.provider = openaisaiku.ai.ask.endpoint = http://litellm.internal:4000/v1/chat/completionssaiku.ai.ask.model = claude-sonnet-3-5# env OPENAI_API_KEY = <any-value-litellm-passes-through>O mesmo truque funciona para qualquer modelo do Bedrock (Titan, Cohere, Mistral, Llama) e para GCP Vertex AI, Databricks Model Serving e todo outro provedor que o LiteLLM cobre.
Modelos auto-hospedados
Qualquer host que fale a Chat Completions API da OpenAI entra direto. Os comuns:
- vLLM — inferência auto-hospedada em GPU; compatível com OpenAI de fábrica.
- Ollama — desenvolvimento local; habilite o adaptador de
compatibilidade com OpenAI usando
OLLAMA_HOST=0.0.0.0. - Together e Groq — endpoints SaaS compatíveis com OpenAI para hospedar modelos em autosserviço.
- LiteLLM — proxy que coloca qualquer coisa na frente (Bedrock, Vertex, Azure, Anthropic, centenas de outros) como compatível com OpenAI.
saiku.ai.ask.provider = openaisaiku.ai.ask.endpoint = https://my.vllm.internal/v1/chat/completionssaiku.ai.ask.model = mistralai/Mistral-7B-Instruct-v0.3# env OPENAI_API_KEY = <any-value-your-server-accepts>O endpoint
POST /saiku/api/ai/askRequisição
{ "question": "show sales by country last quarter", "cube": { "connectionName": "foodmart", "catalog": "FoodMart", "schema": "FoodMart", "cubeName": "Sales" }, "history": [ { "role": "user", "content": "earlier question" }, { "role": "assistant", "content": "earlier summary" } ], "cellsetDigest": "| Country | Store Sales |\n|---|---|\n| USA | 565,238.13 |", "forceTool": "query"}Só question e cube são obrigatórios.
history — voltas (user, assistant) anteriores, mandadas de volta
ao modelo para que acompanhamentos do tipo “agora quebra por região”
se resolvam contra a pergunta anterior. Os prompts de sistema são
controlados pelo servidor; quem chama não consegue injetá-los.
cellsetDigest — um resumo em markdown do resultado que o usuário
está olhando agora. Este pesa mais do que parece:
forceTool — fixar a volta numa intenção em vez de deixar o modelo
escolher. query, insight, view_change ou dashboard; omita (ou
mande auto) para o modelo rotear. A gaveta do workspace expõe isso
como um seletor Auto / Query / Insight / View.
dashboard é a exceção: nunca faz parte do auto e só é alcançável
pedindo explicitamente.
Resposta
A resposta carrega exatamente uma intenção em caso de sucesso. Qual
delas depende de como o modelo roteou a volta — então ramifique por
presença, não assuma que request está sempre lá:
| Campo | Presente quando | Carrega |
|---|---|---|
request + response + queryModel | O modelo respondeu com uma consulta | A requisição tipada, o resultado executado e o modelo de consulta estruturado |
insight | O modelo respondeu com um insight | Análise em markdown do cellset que você mandou |
viewChange | O modelo respondeu com uma mudança de visão | Um modo de visão alvo + tipo de gráfico |
emailDraft | O modelo compôs um e-mail — e o e-mail está configurado | Um corpo de rascunho. Só rascunho; o envio passa pelo endpoint normal de e-mail, nunca por este |
Além disso, em toda resposta: degraded, model, e reason quando
algo deu errado.
{ "degraded": false, "model": "claude-sonnet-4-6", "request": { /* the structured AiQueryRequest the model emitted */ }, "response": { /* the full AiQueryResponse — same shape as /ai/query */ }, "queryModel": { /* the ThinQueryModel, for hydrating a visual builder */ }, "generatedMdx": "SELECT NON EMPTY ... FROM [Sales]"}request é a consulta estruturada que o modelo produziu. Passe-a tal
qual para POST /ai/query para reexecutar, ou
mostre ao usuário como “a consulta tipada por trás da sua pergunta”.
response é o resultado executado, no mesmo formato que a AI Query API
tipada devolve. Se o modelo emitiu uma requisição que o schema rejeita,
response.status é VALIDATION_ERROR e o corpo carrega field +
candidatos available — a gaveta do workspace renderiza isso como chips
clicáveis para o usuário se autocorrigir.
queryModel é o mesmo modelo estruturado que os chips da bancada
manipulam. É o que faz o Editar no canvas devolver uma consulta que
o usuário pode continuar arrastando, em vez de um paredão de MDX no qual
ele não consegue mexer. Ausente nos caminhos degradados e onde a
conversão falhou antes de produzir um.
generatedMdx é um espelho conveniente de
response.metadata.generatedMdx.
Códigos de status
| HTTP | Quando |
|---|---|
200 | A tradução deu certo; response carrega o resultado executado (ou VALIDATION_ERROR para o usuário se autocorrigir). |
200 + degraded:true | A tradução falhou na camada do provedor — erro de transporte, o modelo recusou, ou erro de parse. reason carrega a explicação. |
400 | Falta question ou cube no corpo. |
503 + degraded:true | O provedor é noop (não configurado) — reason explica como habilitar. |
Exemplos
Desligado por padrão — retorno claro
curl -sS -X POST -H 'Content-Type: application/json' \ -u admin:admin \ http://localhost:8080/saiku/api/ai/ask \ -d '{"question":"show sales by country","cube":{"connectionName":"foodmart","catalog":"FoodMart","schema":"FoodMart","cubeName":"Sales"}}'
# {# "degraded": true,# "reason": "AI ask is not configured. Set saiku.ai.ask.provider..."# }Caminho feliz — round-trip completo
curl -sS -X POST -H 'Content-Type: application/json' \ -u admin:admin \ http://localhost:8080/saiku/api/ai/ask \ -d '{"question":"show sales by country","cube":{"connectionName":"foodmart","catalog":"FoodMart","schema":"FoodMart","cubeName":"Sales"}}' \ | jq '{model, generatedMdx, rows: .response.totalRows}'
# {# "model": "claude-sonnet-4-6",# "generatedMdx": "SELECT NON EMPTY {[Measures].[Store Sales]} ON COLUMNS, NON EMPTY {[Customers].[Country].Members} ON ROWS FROM [Sales]",# "rows": 3# }Acompanhamento — múltiplas voltas
curl -sS -X POST -H 'Content-Type: application/json' \ -u admin:admin \ http://localhost:8080/saiku/api/ai/ask \ -d @- <<'EOF'{ "question": "now break it down by quarter", "cube": {"connectionName":"foodmart","catalog":"FoodMart","schema":"FoodMart","cubeName":"Sales"}, "history": [ {"role":"user","content":"show sales by country"}, {"role":"assistant","content":"3 rows returned."} ]}EOFO modelo vê a volta anterior e resolve “por trimestre” como cruzado também com país — o mesmo formato da primeira resposta com uma hierarquia a mais.
Variante em streaming — POST /ai/ask/stream (saiku#1433)
Endpoint companheiro que fala Server-Sent Events para que superfícies de chat embutidas consigam desenhar o progresso conforme ele chega, em vez de travar no round-trip inteiro. Mesmo corpo de requisição, mesma auth, mesmos limites de taxa, mesmo formato de envelope — a resposta é um fluxo de eventos tipados em vez de um único blob JSON.
Esquema de eventos
event: modeldata: {"model":"claude-sonnet-4-6"}
event: intentdata: {"kind":"INSIGHT"}
event: chunkdata: {"delta":"Store "}
event: chunkdata: {"delta":"Sales trended up 12% week-on-week."}
event: finaldata: {"degraded":false,"model":"claude-sonnet-4-6","insight":{"markdown":"Store Sales trended up 12% week-on-week."}}| Evento | Quando | Payload |
|---|---|---|
model | Sempre dispara primeiro quando o provedor devolveu um id de modelo | {"model": "<id>"} |
intent | Depois do roteamento de ferramenta, antes do payload | {"kind": "QUERY" | "INSIGHT" | "VIEW_CHANGE"} |
chunk | Zero ou mais vezes para intenções que carregam prosa (INSIGHT, VIEW_CHANGE.reason) | {"delta": "<pedaço na fronteira de palavra>"} — concatenar deltas não perde nada |
final | Sempre dispara por último em caso de sucesso | Envelope AskResponse completo — mesmo formato do /ai/ask síncrono |
error | Falha de transporte / parse / auth do provedor | {"reason": "<explicação>"} — seguido de um final com degraded:true |
Exemplos de cliente
EventSource só faz GET, então corpos POST passam por fetch +
parse manual de eventos:
const res = await fetch('/rest/saiku/api/ai/ask/stream', { method: 'POST', headers: { 'content-type': 'application/json', accept: 'text/event-stream', }, credentials: 'include', body: JSON.stringify({ question, cube }),});
const reader = res.body!.getReader();const decoder = new TextDecoder();let buffer = '';let markdown = '';
while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); // Events are separated by a blank line (double-newline). const events = buffer.split('\n\n'); buffer = events.pop() ?? ''; for (const raw of events) { const evt = parseSseEvent(raw); if (evt.event === 'chunk') { markdown += JSON.parse(evt.data).delta; render(markdown); } else if (evt.event === 'final') { const full = JSON.parse(evt.data); renderFinal(full); } else if (evt.event === 'error') { showError(JSON.parse(evt.data).reason); } }}
function parseSseEvent(raw: string) { let event = 'message', data = ''; for (const line of raw.split('\n')) { if (line.startsWith('event: ')) event = line.slice(7); else if (line.startsWith('data: ')) data += (data ? '\n' : '') + line.slice(6); } return { event, data };}Qualquer cliente SSE serve — este endpoint devolve um fluxo de
eventos tipados, não os pedaços com sabor Vercel que o AI SDK espera
nativamente, então você escreveria um adaptador pequeno que traduz
os nossos eventos chunk para o que a sua camada de renderização
consome.
async function* saikuAskStream(body: unknown) { const res = await fetch('/rest/saiku/api/ai/ask/stream', { method: 'POST', headers: { 'content-type': 'application/json', accept: 'text/event-stream' }, credentials: 'include', body: JSON.stringify(body), }); // Yield each delta as the caller consumes them. for await (const evt of parseSseStream(res.body!)) { if (evt.event === 'chunk') yield JSON.parse(evt.data).delta as string; }}Útil para depurar localmente:
curl -N -X POST -u admin:admin \ -H 'content-type: application/json' \ -H 'accept: text/event-stream' \ http://localhost:8080/rest/saiku/api/ai/ask/stream \ -d '{"question":"what is trending?","cube":{...}}'O -N desliga o buffer do curl para os eventos saírem conforme
chegam.
Nginx / proxy reverso
Defina X-Accel-Buffering: no (o Saiku já manda) e desligue o buffer de
proxy no seu proxy reverso para os eventos saírem de ponta a ponta:
location /rest/saiku/api/ai/ask/stream { proxy_pass http://saiku:8080; proxy_buffering off; proxy_set_header Connection ''; proxy_http_version 1.1; chunked_transfer_encoding off;}O que o modelo vê e o que não vê
A camada ask manda ao modelo apenas:
- O
AiSchemado cubo ativo — JSON serializado das medidas, dimensões, hierarquias, níveis e membros de amostra. - O JSON Schema do
AiQueryRequestcomoinput_schemada ferramenta de saída estruturada. - A pergunta do usuário e qualquer histórico de conversa que quem chamou tenha anexado.
O modelo é forçado via tool_choice a chamar a ferramenta emit_query
com um formato AiQueryRequest válido. Respostas em prosa crua são
rejeitadas como degradadas.
Ele nunca vê:
- Outros cubos aos quais o usuário tem acesso — só o nomeado na requisição.
- O SQL por baixo nem as credenciais do warehouse.
- Histórico de conversa de outros usuários.
- A requisição HTTP, cookies de sessão, nem qualquer header que quem chamou mandou.
Este é o mesmo modelo de isolamento que o servidor MCP e a AI Query API tipada usam, aplicado uma camada antes.
Endpoints companheiros
O endpoint ask fica ao lado de alguns helpers tipados na mesma
superfície /rest/saiku/api/ai/*. Agentes os usam para resolver nomes
antes de perguntar, rodar uma simulação, ou ajudar um operador a fechar
a governança.
GET /ai/members/search — resolver o nome de um membro
Antes de referenciar um membro numa consulta ou filtro, procure o nome único exato dele com uma busca de substring que ignora maiúsculas. Espelha a busca de valores do lado OSSIE.
| Parâmetro | Obrigatório | Notas |
|---|---|---|
cubeId | sim | connection/catalog/schema/cube |
dimension | sim | Nome da dimensão |
hierarchy | não | Nome da hierarquia (padrão: a hierarquia padrão da dimensão) |
level | sim | Nível onde procurar |
q | não | String de busca; omita para paginar os primeiros membros |
limit | não | Máximo de acertos (padrão 20) |
curl -sS -u admin:admin \ 'http://localhost:8080/saiku/api/ai/members/search?cubeId=foodmart/FoodMart/FoodMart/Sales&dimension=Product&level=Product%20Family&q=drink&limit=10'# → [ { "uniqueName": "[Product].[Drink]", "caption": "Drink", ... }, … ]POST /ai/scenario/whatif — simulação com write-back
Coloque a medida de um membro num valor alvo, reexecute a consulta
dentro de um cenário novo do Mondrian, e receba real versus what-if
para cada irmão e total conforme o motor redistribui o delta. O cubo
precisa declarar
enableScenarios="true".
curl -sS -X POST -H 'Content-Type: application/json' \ -u admin:admin \ http://localhost:8080/saiku/api/ai/scenario/whatif \ -d '{ "connection": "foodmart", "cube": "Sales", "level": "[Product].[Product Family]", "measure": "Store Sales", "member": "[Product].[Drink]", "value": 50000, "policy": "EQUAL_ALLOCATION" }'level e member são nomes únicos de MDX; value é o novo valor
absoluto da medida para member; policy é EQUAL_ALLOCATION por
padrão.
GET /ai/schema/{cubeId}/pii-suggestions — helper de governança
Só para admins. Varre o cubo descrito atrás de colunas que batem com
um padrão de PII mas ainda não estão anotadas com pii=true, para um
operador conseguir fechar a redação de PII sem
greppar logs. Deliberadamente separado da visão de schema voltada a
agentes — agentes nunca veem a política em rascunho do operador. Devolve
uma lista vazia (não um 404) para um cubo que ainda não foi descrito.
curl -sS -u admin:admin \ http://localhost:8080/saiku/api/ai/schema/foodmart/FoodMart/FoodMart/Sales/pii-suggestions# → { "suggestions": [ { "field": "customer_email", "reason": "matches email pattern" }, … ] }Skills — fluxos escritos pelo administrador
Skills são arquivos markdown com frontmatter YAML sob
saiku-home/skills/ que qualquer volta de /ai/ask pode invocar pelo
nome (/weekly-rollup for Q4) ou por correspondência em linguagem
natural. Referência completa em Agent Skills.
Agent Spaces — asks escopados por persona
Spaces são personas nomeadas, escritas pelo administrador (“Sales
Analyst”, “Finance Ops”), que escopam uma superfície de ask inteira —
prompt de sistema, allowlist de cubos, allowlist de skills, prompts
sugeridos. POST /ai/spaces/{id}/ask usa o mesmo envelope que este
endpoint, com aplicação do escopo no servidor por cima. Referência
completa em Agent Spaces.
Para onde ir depois
- Agent Skills — fluxos em markdown escritos pelo
administrador, descobríveis a partir de qualquer volta de
/ai/ask. - Agent Spaces — personas que fixam a allowlist de cubos, filtram o catálogo de skills e injetam um prompt de sistema.
- Agent evals — harness de ground truth em YAML para pegar regressões de AI ask quando o provedor LLM, o modelo ou o prompt mudam.
- AI Query API — a superfície tipada para a qual
o
/ai/asktraduz. Útil quando você quer um agente (não uma pessoa) escrevendo a requisição. - Servidor MCP — a mesma superfície tipada exposta como ferramentas MCP para agentes Claude Desktop / Cursor / Cline.
- Autenticação — Bearer tokens, limites de taxa, formatos de erro.