AI Ask API
La AI Ask API toma una pregunta en lenguaje llano, pide al proveedor LLM configurado que rellene una consulta tipada contra el schema vivo del cubo, pasa esa consulta por el mismo conversor que usa la AI Query API tipada, y devuelve el resultado ejecutado + el MDX generado + la petición estructurada que emitió el modelo.
Es la capa de lenguaje natural que se sienta encima de la superficie
tipada para agentes. Donde la API tipada asume que quien llama habla
AiQueryRequest, la ask API deja que una persona diga «muéstrame las
ventas por país el trimestre pasado» y reciba un cellset completamente
ejecutado, con la traducción del modelo visible al lado.
Esto mueve el panel AI Query del workspace — el botón ⚡ de la barra de herramientas abre un panel de chat donde los usuarios escriben preguntas y pulsan Editar en canvas para dejar el resultado en la pestaña de consulta activa.
Cuándo usarla
La ask API es la superficie correcta cuando:
- Los usuarios finales van a escribir preguntas — la AI Query API tipada espera un agente que ya conozca el schema del cubo; la ask API esconde ese paso tras un LLM.
- Quiere un round-trip por pregunta —
/ai/askhace traducción + ejecución + formado del sobre en una sola llamada, así el cliente no tiene que encadenar dos APIs. - Está incrustando una superficie tipo chat — el campo multivuelta
historydeja que las preguntas de seguimiento se resuelvan contra turnos anteriores.
Cuándo no usarla:
- Agentes en el servidor MCP — los agentes prefieren la superficie tipada porque ya se les da bien rellenar campos estructurados a partir de un JSON Schema. La capa ask es para personas.
- Crear cubos desde un warehouse de muestra — use la AI Inference API, diseñada para el flujo de diseño.
Activación
Dos propiedades + una variable de entorno por proveedor. Ambas pueden fijarse en la JVM o en el archivo de propiedades del despliegue que lee Spring.
# 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_SECONDSValores por defecto de cada proveedor:
| Proveedor | Modelo por defecto | 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 | (sin defecto) | (sin defecto — se niega a construirse sin una 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 un Secret para la clave y un ConfigMap para el nombre del
proveedor:
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 — traiga su propio modelo (saiku#1431)
Los despliegues enterprise a menudo no pueden mandar prompts a Anthropic u OpenAI directamente — el LLM tiene que correr dentro de la VPC del cliente o detrás de sus compras ya aprobadas. La capa ask cubre las tres formas de BYOLLM más comunes sin meter dependencias pesadas en Saiku.
| Forma | Proveedor | Formato del endpoint | Cabecera de auth |
|---|---|---|---|
| Azure OpenAI Service | azure-openai | https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=<v> | api-key: <key> |
| Autoalojado / proxy compatible con OpenAI (vLLM, Ollama, LiteLLM, Together, Groq) | openai | cualquier URL que hable la Chat Completions API de OpenAI | Authorization: Bearer <key> |
| AWS Bedrock con LiteLLM delante | openai | LiteLLM delante de Bedrock (https://litellm.internal/v1/chat/completions) | Authorization: Bearer <litellm-key> |
El adaptador nativo azure-openai se encarga de las dos cosas
específicas de Azure (nombre de deployment en la URL y cabecera
api-key) para que los operadores no tengan que montar un proxy de
traducción en el caso más común.
Activación de Azure OpenAI
-
Despliegue un modelo compatible con OpenAI en su recurso de Azure OpenAI. Anote el nombre del recurso y el del deployment.
-
Saque una clave del portal de Azure → su recurso → Keys and Endpoint.
-
Fije en el 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> -
Arranque el launcher. Una línea INFO al inicio confirma el cableado:
INFO o.s.s.o.a.a.NlAskProviderFactory - AI ask provider: azure-openai (deployment/model=my-deployment, endpoint=https://…)
AWS Bedrock vía LiteLLM
El patrón recomendado para Bedrock es correr
LiteLLM como front compatible con OpenAI y
apuntar el proveedor openai que Saiku ya tiene a LiteLLM. LiteLLM se
encarga del firmado SigV4 aguas arriba, así Saiku no necesita el SDK de
AWS en su 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 4000Y luego, del lado de 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>El mismo truco vale para cualquier modelo de Bedrock (Titan, Cohere, Mistral, Llama) y para GCP Vertex AI, Databricks Model Serving y cualquier otro proveedor que cubra LiteLLM.
Modelos autoalojados
Cualquier host que hable la Chat Completions API de OpenAI encaja directo. Los habituales:
- vLLM — inferencia autoalojada en GPU; compatible con OpenAI de serie.
- Ollama — desarrollo local; active el adaptador de compatibilidad
con OpenAI con
OLLAMA_HOST=0.0.0.0. - Together y Groq — endpoints SaaS compatibles con OpenAI para alojar modelos en autoservicio.
- LiteLLM — proxy que pone por delante cualquier cosa (Bedrock, Vertex, Azure, Anthropic, cientos más) como compatible con 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>El endpoint
POST /saiku/api/ai/askPetición
{ "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"}Solo question y cube son obligatorios.
history — turnos (user, assistant) anteriores, reenviados al
modelo para que los seguimientos del tipo «ahora desglósalo por
región» se resuelvan contra la pregunta anterior. Los prompts de
sistema los controla el servidor; quien llama no puede inyectarlos.
cellsetDigest — un resumen en markdown del resultado que el
usuario está mirando ahora mismo. Éste importa más de lo que parece:
forceTool — fijar el turno a una intención en lugar de dejar
elegir al modelo. query, insight, view_change o dashboard;
omítalo (o mande auto) para que el modelo enrute. El panel del
workspace lo expone como un selector Auto / Query / Insight / View.
dashboard es la excepción: nunca forma parte de auto y solo se
alcanza pidiéndolo explícitamente.
Respuesta
La respuesta lleva exactamente una intención cuando tiene éxito.
Cuál, depende de cómo enrutó el modelo el turno — así que ramifique por
presencia, no asuma que request está siempre:
| Campo | Presente cuando | Lleva |
|---|---|---|
request + response + queryModel | El modelo respondió con una consulta | La petición tipada, el resultado ejecutado y el modelo de consulta estructurado |
insight | El modelo respondió con un insight | Análisis en markdown del cellset que mandó |
viewChange | El modelo respondió con un cambio de vista | Un modo de vista destino + tipo de gráfico |
emailDraft | El modelo compuso un correo — y el correo está configurado | Un cuerpo de borrador. Solo borrador; el envío pasa por el endpoint normal de correo, nunca por éste |
Además, en toda respuesta: degraded, model, y reason cuando algo
salió mal.
{ "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 es la consulta estructurada que produjo el modelo. Pásela tal
cual a POST /ai/query para reejecutarla, o
muéstresela al usuario como «la consulta tipada detrás de su pregunta».
response es el resultado ejecutado, con la misma forma que devuelve la
AI Query API tipada. Si el modelo emitió una petición que el schema
rechaza, response.status es VALIDATION_ERROR y el cuerpo lleva
field + candidatos available — el panel del workspace los dibuja
como chips pulsables para que el usuario se autocorrija.
queryModel es el mismo modelo estructurado que manipulan los chips del
banco de trabajo. Es lo que hace que Editar en canvas devuelva una
consulta que el usuario puede seguir arrastrando, en vez de un muro de
MDX que no puede. Ausente en los caminos degradados y allí donde la
conversión falló antes de producir uno.
generatedMdx es un espejo cómodo de
response.metadata.generatedMdx.
Códigos de estado
| HTTP | Cuándo |
|---|---|
200 | La traducción tuvo éxito; response lleva el resultado ejecutado (o VALIDATION_ERROR para que el usuario se autocorrija). |
200 + degraded:true | La traducción falló en la capa del proveedor — error de transporte, el modelo se negó, o error de parseo. reason lleva la explicación. |
400 | Falta question o cube en el cuerpo. |
503 + degraded:true | El proveedor es noop (sin configurar) — reason explica cómo activarlo. |
Ejemplos
Desactivado por defecto — respuesta clara
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..."# }Camino 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# }Seguimiento — multivuelta
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."} ]}EOFEl modelo ve el turno anterior y resuelve «por trimestre» como cruzado también contra país — la misma forma que la primera respuesta con una jerarquía extra.
Variante en streaming — POST /ai/ask/stream (saiku#1433)
Endpoint acompañante que habla Server-Sent Events para que las superficies de chat incrustadas puedan dibujar el progreso según llega, en lugar de bloquearse en el round-trip completo. Mismo cuerpo de petición, misma auth, mismos límites de tasa, misma forma de sobre — la respuesta es un flujo de eventos tipados en vez de un ú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 | Cuándo | Payload |
|---|---|---|
model | Siempre dispara primero cuando el proveedor devolvió un id de modelo | {"model": "<id>"} |
intent | Tras el enrutado de herramienta, antes del payload | {"kind": "QUERY" | "INSIGHT" | "VIEW_CHANGE"} |
chunk | Cero o más veces en intenciones que llevan prosa (INSIGHT, VIEW_CHANGE.reason) | {"delta": "<trozo en frontera de palabra>"} — concatenar deltas no pierde nada |
final | Siempre dispara el último si hay éxito | Sobre AskResponse completo — misma forma que /ai/ask síncrono |
error | Fallo de transporte / parseo / auth del proveedor | {"reason": "<explicación>"} — seguido de un final con degraded:true |
Ejemplos de cliente
EventSource solo hace GET, así que los cuerpos POST van por
fetch + parseo 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 };}Vale cualquier cliente SSE — este endpoint devuelve un flujo de
eventos tipados, no los trozos con sabor Vercel que el AI SDK espera
de forma nativa, así que escribiría un pequeño adaptador que
traduzca nuestros eventos chunk a lo que consuma su capa de
renderizado.
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; }}Práctico para depurar en local:
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":{...}}'El -N desactiva el búfer de curl para que los eventos salgan según
llegan.
Nginx / proxy inverso
Fije X-Accel-Buffering: no (Saiku ya lo manda) y desactive el búfer
del proxy en su proxy inverso para que los eventos salgan de punta a
punta:
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;}Qué ve el modelo y qué no
La capa ask manda al modelo solo:
- El
AiSchemadel cubo activo — JSON serializado de medidas, dimensiones, jerarquías, niveles y miembros de muestra. - El JSON Schema de
AiQueryRequestcomoinput_schemade la herramienta de salida estructurada. - La pregunta del usuario y el historial de conversación que haya adjuntado quien llama.
Al modelo se le obliga vía tool_choice a llamar a la herramienta
emit_query con una forma AiQueryRequest válida. Las respuestas en
prosa cruda se rechazan como degradadas.
Nunca ve:
- Otros cubos a los que el usuario tenga acceso — solo el nombrado en la petición.
- El SQL subyacente ni las credenciales del warehouse.
- El historial de conversación de otros usuarios.
- La petición HTTP, las cookies de sesión, ni ninguna cabecera que mandara quien llama.
Éste es el mismo modelo de aislamiento que usan el servidor MCP y la AI Query API tipada, aplicado una capa antes.
Endpoints acompañantes
El endpoint ask convive con unos cuantos helpers tipados en la misma
superficie /rest/saiku/api/ai/*. Los agentes los usan para resolver
nombres antes de preguntar, correr una simulación, o ayudar a un
operador a asegurar la gobernanza.
GET /ai/members/search — resolver el nombre de un miembro
Antes de referenciar un miembro en una consulta o un filtro, busque su nombre único exacto con una búsqueda de subcadena que ignora mayúsculas. Espeja la búsqueda de valores del lado OSSIE.
| Parámetro | Obligatorio | Notas |
|---|---|---|
cubeId | sí | connection/catalog/schema/cube |
dimension | sí | Nombre de la dimensión |
hierarchy | no | Nombre de la jerarquía (por defecto, la de la dimensión) |
level | sí | Nivel en el que buscar |
q | no | Cadena de búsqueda; omítala para paginar los primeros miembros |
limit | no | Máximo de aciertos (por defecto 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 — simulación con write-back
Fije la medida de un miembro a un valor objetivo, reejecute la consulta
dentro de un escenario de Mondrian nuevo, y obtenga real frente a
what-if para cada hermano y total mientras el motor reasigna el delta.
El cubo debe 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 y member son nombres únicos de MDX; value es el nuevo valor
absoluto de la medida para member; policy es EQUAL_ALLOCATION por
defecto.
GET /ai/schema/{cubeId}/pii-suggestions — helper de gobernanza
Solo para admins. Escanea el cubo descrito buscando columnas que
coinciden con un patrón de PII pero aún no están anotadas con
pii=true, para que un operador pueda asegurar la redacción de
PII sin greppear logs. Deliberadamente separado de
la vista de schema que ven los agentes — los agentes nunca ven la
política en borrador del operador. Devuelve una lista vacía (no un 404)
para un cubo que aún no se ha 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 — flujos escritos por el administrador
Las skills son archivos markdown con frontmatter YAML bajo
saiku-home/skills/ que cualquier turno de /ai/ask puede invocar por
nombre (/weekly-rollup for Q4) o por coincidencia en lenguaje natural.
Referencia completa en Agent Skills.
Agent Spaces — asks acotados por persona
Los spaces son personas con nombre, escritas por el administrador
(«Sales Analyst», «Finance Ops»), que acotan toda una superficie de ask
— prompt de sistema, lista de cubos permitidos, lista de skills
permitidas, prompts sugeridos. POST /ai/spaces/{id}/ask usa el mismo
sobre que este endpoint, con aplicación del alcance en el servidor por
encima. Referencia completa en Agent Spaces.
Adónde ir después
- Agent Skills — flujos markdown escritos por el
administrador, descubribles desde cualquier turno de
/ai/ask. - Agent Spaces — personas que fijan la lista de cubos permitidos, filtran el catálogo de skills e inyectan un prompt de sistema.
- Agent evals — arnés de verdad-de-campo en YAML para cazar regresiones de AI ask cuando cambian el proveedor LLM, el modelo o el prompt.
- AI Query API — la superficie tipada a la que
/ai/asktraduce. Útil cuando quiere que un agente (no una persona) redacte la petición. - Servidor MCP — la misma superficie tipada expuesta como herramientas MCP para agentes de Claude Desktop / Cursor / Cline.
- Autenticación — tokens Bearer, límites de tasa, formas de error.