Pular para o conteúdo

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/ask faz 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 history deixa 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 Claude
saiku.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-openai
saiku.ai.ask.endpoint = https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=2024-02-15-preview
saiku.ai.ask.model = <deployment>
# env AZURE_OPENAI_API_KEY = <azure-key>
# Optional, all providers
saiku.ai.ask.model = claude-sonnet-4-6 | gpt-4o-mini | ...
saiku.ai.ask.endpoint = https://my.openai-compatible.host/v1/chat/completions
saiku.ai.ask.apiKey = ... # explicit override of the env var
saiku.ai.ask.timeoutSeconds = 60 # or env SAIKU_AI_ASK_TIMEOUT_SECONDS

Padrões por provedor:

ProvedorModelo padrãoEndpoint
anthropicclaude-sonnet-4-6https://api.anthropic.com/v1/messages
openaigpt-4o-minihttps://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

Terminal window
docker run -d --name saiku \
-e ANTHROPIC_API_KEY=sk-ant-... \
-e JAVA_OPTS='-Dsaiku.ai.ask.provider=anthropic' \
ghcr.io/spiculedata/saiku:latest

Kubernetes

Use um Secret para a chave e um ConfigMap para o nome do provedor:

apiVersion: v1
kind: Secret
metadata:
name: saiku-ai
type: Opaque
stringData:
ANTHROPIC_API_KEY: sk-ant-...
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: saiku
spec:
template:
spec:
containers:
- name: saiku
envFrom:
- secretRef:
name: saiku-ai
env:
- name: JAVA_OPTS
value: -Dsaiku.ai.ask.provider=anthropic

BYOLLM — 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.

FormatoProvedorFormato do endpointHeader de auth
Azure OpenAI Serviceazure-openaihttps://<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)openaiqualquer URL que fale a Chat Completions API da OpenAIAuthorization: Bearer <key>
AWS Bedrock com LiteLLM na frenteopenaiLiteLLM 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

  1. Faça deploy de um modelo compatível com OpenAI no seu recurso Azure OpenAI. Anote o nome do recurso e o do deployment.

  2. Pegue uma chave no portal da Azure → seu recurso → Keys and Endpoint.

  3. Defina no launcher:

    saiku.ai.ask.provider = azure-openai
    saiku.ai.ask.endpoint = https://my-resource.openai.azure.com/openai/deployments/my-deployment/chat/completions?api-version=2024-02-15-preview
    saiku.ai.ask.model = my-deployment
    # env AZURE_OPENAI_API_KEY = <azure-api-key>
  4. 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.

litellm-config.yaml
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: true
Terminal window
litellm --config litellm-config.yaml --port 4000

E então, do lado do Saiku:

saiku.ai.ask.provider = openai
saiku.ai.ask.endpoint = http://litellm.internal:4000/v1/chat/completions
saiku.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 = openai
saiku.ai.ask.endpoint = https://my.vllm.internal/v1/chat/completions
saiku.ai.ask.model = mistralai/Mistral-7B-Instruct-v0.3
# env OPENAI_API_KEY = <any-value-your-server-accepts>

O endpoint

POST /saiku/api/ai/ask

Requisiçã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á:

CampoPresente quandoCarrega
request + response + queryModelO modelo respondeu com uma consultaA requisição tipada, o resultado executado e o modelo de consulta estruturado
insightO modelo respondeu com um insightAnálise em markdown do cellset que você mandou
viewChangeO modelo respondeu com uma mudança de visãoUm modo de visão alvo + tipo de gráfico
emailDraftO modelo compôs um e-mail — e o e-mail está configuradoUm 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

HTTPQuando
200A tradução deu certo; response carrega o resultado executado (ou VALIDATION_ERROR para o usuário se autocorrigir).
200 + degraded:trueA tradução falhou na camada do provedor — erro de transporte, o modelo recusou, ou erro de parse. reason carrega a explicação.
400Falta question ou cube no corpo.
503 + degraded:trueO provedor é noop (não configurado) — reason explica como habilitar.

Exemplos

Desligado por padrão — retorno claro

Terminal window
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

Terminal window
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

Terminal window
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."}
]
}
EOF

O 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: model
data: {"model":"claude-sonnet-4-6"}
event: intent
data: {"kind":"INSIGHT"}
event: chunk
data: {"delta":"Store "}
event: chunk
data: {"delta":"Sales trended up 12% week-on-week."}
event: final
data: {"degraded":false,"model":"claude-sonnet-4-6","insight":{"markdown":"Store Sales trended up 12% week-on-week."}}
EventoQuandoPayload
modelSempre dispara primeiro quando o provedor devolveu um id de modelo{"model": "<id>"}
intentDepois do roteamento de ferramenta, antes do payload{"kind": "QUERY" | "INSIGHT" | "VIEW_CHANGE"}
chunkZero 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
finalSempre dispara por último em caso de sucessoEnvelope AskResponse completo — mesmo formato do /ai/ask síncrono
errorFalha 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 };
}

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 AiSchema do cubo ativo — JSON serializado das medidas, dimensões, hierarquias, níveis e membros de amostra.
  • O JSON Schema do AiQueryRequest como input_schema da 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âmetroObrigatórioNotas
cubeIdsimconnection/catalog/schema/cube
dimensionsimNome da dimensão
hierarchynãoNome da hierarquia (padrão: a hierarquia padrão da dimensão)
levelsimNível onde procurar
qnãoString de busca; omita para paginar os primeiros membros
limitnãoMáximo de acertos (padrão 20)
Terminal window
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".

Terminal window
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.

Terminal window
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/ask traduz. Ú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.