Saltearse al contenido

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/ask hace 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 history deja 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 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

Valores por defecto de cada proveedor:

ProveedorModelo por defectoEndpoint
anthropicclaude-sonnet-4-6https://api.anthropic.com/v1/messages
openaigpt-4o-minihttps://api.openai.com/v1/chat/completions
azure-openai(sin defecto)(sin defecto — se niega a construirse sin una URL de deployment explícita)

Docker

Ventana de terminal
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 un Secret para la clave y un ConfigMap para el nombre del proveedor:

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

FormaProveedorFormato del endpointCabecera de auth
Azure OpenAI Serviceazure-openaihttps://<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)openaicualquier URL que hable la Chat Completions API de OpenAIAuthorization: Bearer <key>
AWS Bedrock con LiteLLM delanteopenaiLiteLLM 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

  1. Despliegue un modelo compatible con OpenAI en su recurso de Azure OpenAI. Anote el nombre del recurso y el del deployment.

  2. Saque una clave del portal de Azure → su recurso → Keys and Endpoint.

  3. Fije en el 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. 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.

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
Ventana de terminal
litellm --config litellm-config.yaml --port 4000

Y luego, del lado de 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>

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 = 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>

El endpoint

POST /saiku/api/ai/ask

Petició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:

CampoPresente cuandoLleva
request + response + queryModelEl modelo respondió con una consultaLa petición tipada, el resultado ejecutado y el modelo de consulta estructurado
insightEl modelo respondió con un insightAnálisis en markdown del cellset que mandó
viewChangeEl modelo respondió con un cambio de vistaUn modo de vista destino + tipo de gráfico
emailDraftEl modelo compuso un correo — y el correo está configuradoUn 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

HTTPCuándo
200La traducción tuvo éxito; response lleva el resultado ejecutado (o VALIDATION_ERROR para que el usuario se autocorrija).
200 + degraded:trueLa traducción falló en la capa del proveedor — error de transporte, el modelo se negó, o error de parseo. reason lleva la explicación.
400Falta question o cube en el cuerpo.
503 + degraded:trueEl proveedor es noop (sin configurar) — reason explica cómo activarlo.

Ejemplos

Desactivado por defecto — respuesta clara

Ventana de terminal
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

Ventana de terminal
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

Ventana de terminal
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

El 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: 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."}}
EventoCuándoPayload
modelSiempre dispara primero cuando el proveedor devolvió un id de modelo{"model": "<id>"}
intentTras el enrutado de herramienta, antes del payload{"kind": "QUERY" | "INSIGHT" | "VIEW_CHANGE"}
chunkCero o más veces en intenciones que llevan prosa (INSIGHT, VIEW_CHANGE.reason){"delta": "<trozo en frontera de palabra>"} — concatenar deltas no pierde nada
finalSiempre dispara el último si hay éxitoSobre AskResponse completo — misma forma que /ai/ask síncrono
errorFallo 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 };
}

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 AiSchema del cubo activo — JSON serializado de medidas, dimensiones, jerarquías, niveles y miembros de muestra.
  • El JSON Schema de AiQueryRequest como input_schema de 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ámetroObligatorioNotas
cubeIdsíconnection/catalog/schema/cube
dimensionsíNombre de la dimensión
hierarchynoNombre de la jerarquía (por defecto, la de la dimensión)
levelsíNivel en el que buscar
qnoCadena de búsqueda; omítala para paginar los primeros miembros
limitnoMáximo de aciertos (por defecto 20)
Ventana de terminal
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".

Ventana de terminal
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.

Ventana de terminal
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/ask traduce. Ú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.