AI Ask API
L’API AI Ask prend une question en langage courant, demande au fournisseur LLM configuré de remplir une requête typée sur le schema vivant du cube, passe cette requête par le même convertisseur qu’utilise l’API AI Query typée, et renvoie le résultat exécuté + le MDX généré + la requête structurée que le modèle a émise.
C’est la couche langage naturel posée sur la surface typée pour agents.
Là où l’API typée suppose que l’appelant parle AiQueryRequest, l’API
ask laisse un humain dire « montre-moi les ventes par pays au trimestre
dernier » et récupérer un cellset entièrement exécuté, avec la
traduction du modèle visible à côté.
C’est ce qui anime le panneau AI Query du workspace — le bouton ⚡ de la barre d’outils ouvre un panneau de chat où les utilisateurs tapent des questions et cliquent sur Éditer dans le canevas pour déposer le résultat dans l’onglet de requête actif.
Quand l’utiliser
L’API ask est la bonne surface quand :
- Des utilisateurs finaux vont taper des questions — l’API AI Query typée attend un agent qui connaît déjà le schema du cube ; l’API ask cache cette étape derrière un LLM.
- Vous voulez un aller-retour par question —
/ai/askfait traduction + exécution + mise en forme de l’enveloppe en un seul appel, pour que le client n’ait pas à chaîner deux API. - Vous intégrez une surface de type chat — le champ multi-tours
historypermet aux questions de suivi de se résoudre contre les tours précédents.
Quand ne pas l’utiliser :
- Des agents sur le serveur MCP — les agents préfèrent la surface typée, parce qu’ils sont déjà bons pour remplir des champs structurés à partir d’un JSON Schema. La couche ask est pour les humains.
- Créer des cubes depuis un entrepôt d’exemple — utilisez l’API AI Inference, conçue pour le flux de conception.
Activation
Deux propriétés + une variable d’environnement par fournisseur. Les deux peuvent être définies sur la JVM ou dans le fichier de propriétés du déploiement que lit 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_SECONDSValeurs par défaut des fournisseurs :
| Fournisseur | Modèle par défaut | Point d’entrée |
|---|---|---|
anthropic | claude-sonnet-4-6 | https://api.anthropic.com/v1/messages |
openai | gpt-4o-mini | https://api.openai.com/v1/chat/completions |
azure-openai | (aucun défaut) | (aucun défaut — refuse de se construire sans URL de déploiement explicite) |
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
Utilisez un Secret pour la clé, une ConfigMap pour le nom du
fournisseur :
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 — apportez votre propre modèle (saiku#1431)
Les déploiements enterprise ne peuvent souvent pas envoyer de prompts directement à Anthropic ou OpenAI — le LLM doit tourner dans le VPC du client ou derrière ses achats déjà validés. La couche ask couvre les trois formes de BYOLLM les plus courantes sans embarquer de grosses dépendances dans Saiku.
| Forme | Fournisseur | Format du point d’entrée | En-tête d’auth |
|---|---|---|---|
| Azure OpenAI Service | azure-openai | https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=<v> | api-key: <key> |
| Auto-hébergé / proxy compatible OpenAI (vLLM, Ollama, LiteLLM, Together, Groq) | openai | toute URL qui parle l’API Chat Completions d’OpenAI | Authorization: Bearer <key> |
| AWS Bedrock via LiteLLM en façade | openai | LiteLLM devant Bedrock (https://litellm.internal/v1/chat/completions) | Authorization: Bearer <litellm-key> |
L’adaptateur natif azure-openai s’occupe des deux spécificités Azure
(nom de déploiement dans l’URL et en-tête api-key) pour que les
opérateurs n’aient pas à faire tourner un proxy de traduction dans le
cas le plus courant.
Activation d’Azure OpenAI
-
Déployez un modèle compatible OpenAI dans votre ressource Azure OpenAI. Notez le nom de la ressource et celui du déploiement.
-
Récupérez une clé depuis le portail Azure → votre ressource → Keys and Endpoint.
-
Définissez sur le 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> -
Démarrez le launcher. Une ligne INFO au démarrage confirme le câblage :
INFO o.s.s.o.a.a.NlAskProviderFactory - AI ask provider: azure-openai (deployment/model=my-deployment, endpoint=https://…)
AWS Bedrock via LiteLLM
Le motif recommandé pour Bedrock est de faire tourner
LiteLLM en façade compatible OpenAI et de
pointer le fournisseur openai déjà présent dans Saiku vers LiteLLM.
LiteLLM gère la signature SigV4 en amont, Saiku n’a donc pas besoin du
SDK AWS dans son 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 4000Puis, côté 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>La même astuce marche pour n’importe quel modèle Bedrock (Titan, Cohere, Mistral, Llama) ainsi que pour GCP Vertex AI, Databricks Model Serving et tous les autres fournisseurs que couvre LiteLLM.
Modèles auto-hébergés
Tout hôte qui parle l’API Chat Completions d’OpenAI se branche directement. Les plus courants :
- vLLM — inférence GPU auto-hébergée ; compatible OpenAI d’origine.
- Ollama — développement local ; activez l’adaptateur de
compatibilité OpenAI avec
OLLAMA_HOST=0.0.0.0. - Together et Groq — points d’entrée SaaS compatibles OpenAI pour héberger des modèles en self-service.
- LiteLLM — proxy qui met n’importe quoi en façade (Bedrock, Vertex, Azure, Anthropic, des centaines d’autres) en compatible 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>Le point d’entrée
POST /saiku/api/ai/askRequête
{ "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"}Seuls question et cube sont obligatoires.
history — les tours (user, assistant) précédents, renvoyés au
modèle pour que les suivis du type « maintenant découpe par région »
se résolvent contre la question antérieure. Les prompts système sont
contrôlés par le serveur ; les appelants ne peuvent pas les injecter.
cellsetDigest — un condensé markdown du résultat que
l’utilisateur a sous les yeux. Celui-ci compte plus qu’il n’en a l’air :
forceTool — épingler le tour sur une intention au lieu de laisser
le modèle choisir. query, insight, view_change ou dashboard ;
omettez-le (ou envoyez auto) pour laisser le modèle router. Le panneau
du workspace l’expose sous forme de sélecteur Auto / Query / Insight /
View.
dashboard est l’exception : il ne fait jamais partie d’auto et n’est
atteignable qu’en le demandant explicitement.
Réponse
La réponse porte exactement une intention en cas de succès. Laquelle
dépend de la façon dont le modèle a routé le tour — testez donc la
présence, ne supposez pas que request est toujours là :
| Champ | Présent quand | Porte |
|---|---|---|
request + response + queryModel | Le modèle a répondu par une requête | La requête typée, le résultat exécuté, et le modèle de requête structuré |
insight | Le modèle a répondu par un insight | Une analyse markdown du cellset que vous avez envoyé |
viewChange | Le modèle a répondu par un changement de vue | Un mode de vue cible + un type de graphique |
emailDraft | Le modèle a rédigé un e-mail — et le mail est configuré | Un corps de brouillon. Brouillon seulement ; l’envoi passe par le point d’entrée e-mail normal, jamais celui-ci |
Plus, sur chaque réponse : degraded, model, et reason quand
quelque chose a mal tourné.
{ "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 est la requête structurée produite par le modèle.
Passez-la telle quelle à POST /ai/query pour la
réexécuter, ou montrez-la à l’utilisateur comme « la requête typée
derrière votre question ».
response est le résultat exécuté, de la même forme que ce que renvoie
l’API AI Query typée. Si le modèle a émis une requête que le schema
rejette, response.status vaut VALIDATION_ERROR et le corps porte
field + les candidats available — le panneau du workspace les rend
en pastilles cliquables pour que l’utilisateur se corrige tout seul.
queryModel est le même modèle structuré que manipulent les pastilles
de l’établi. C’est ce qui fait qu’Éditer dans le canevas rend une
requête que l’utilisateur peut continuer à glisser, plutôt qu’un mur de
MDX où il ne peut rien faire. Absent sur les chemins dégradés et là où
la conversion a échoué avant d’en produire un.
generatedMdx est un miroir pratique de
response.metadata.generatedMdx.
Codes de statut
| HTTP | Quand |
|---|---|
200 | La traduction a réussi ; response porte le résultat exécuté (ou VALIDATION_ERROR pour que l’utilisateur se corrige). |
200 + degraded:true | La traduction a échoué au niveau du fournisseur — erreur de transport, refus du modèle, ou erreur de parsing. reason porte l’explication. |
400 | question ou cube manquant dans le corps. |
503 + degraded:true | Le fournisseur est noop (non configuré) — reason explique comment l’activer. |
Exemples
Désactivé par défaut — retour clair
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..."# }Cas nominal — aller-retour complet
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# }Suivi — multi-tours
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."} ]}EOFLe modèle voit le tour précédent et résout « par trimestre » comme croisé aussi avec le pays — la même forme que la première réponse avec une hiérarchie de plus.
Variante en streaming — POST /ai/ask/stream (saiku#1433)
Point d’entrée compagnon qui parle Server-Sent Events pour que les surfaces de chat intégrées puissent afficher la progression au fil de l’eau plutôt que de bloquer sur l’aller-retour complet. Même corps de requête, même auth, mêmes limites de débit, même forme d’enveloppe — la réponse est un flux d’événements typés au lieu d’un seul bloc JSON.
Schéma des événements
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."}}| Événement | Quand | Charge utile |
|---|---|---|
model | Se déclenche toujours en premier quand le fournisseur a renvoyé un id de modèle | {"model": "<id>"} |
intent | Après le routage d’outil, avant la charge utile | {"kind": "QUERY" | "INSIGHT" | "VIEW_CHANGE"} |
chunk | Zéro fois ou plus pour les intentions porteuses de prose (INSIGHT, VIEW_CHANGE.reason) | {"delta": "<morceau à la frontière d'un mot>"} — concaténer les deltas est sans perte |
final | Se déclenche toujours en dernier en cas de succès | Enveloppe AskResponse complète — même forme que /ai/ask synchrone |
error | Échec de transport / parsing / auth du fournisseur | {"reason": "<explication>"} — suivi d’un final avec degraded:true |
Exemples côté client
EventSource ne fait que du GET, les corps POST passent donc par
fetch + parsing manuel des événements :
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 };}N’importe quel client SSE convient — ce point d’entrée renvoie un
flux d’événements typés, pas les morceaux à la sauce Vercel que le
AI SDK attend nativement ; vous écririez donc un petit adaptateur
qui traduit nos événements chunk vers ce que consomme votre couche
de rendu.
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; }}Pratique pour déboguer 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":{...}}'Le -N désactive la mise en tampon de curl pour que les événements
sortent au fur et à mesure.
Nginx / reverse proxy
Définissez X-Accel-Buffering: no (Saiku l’envoie déjà) et désactivez
la mise en tampon du proxy sur votre reverse proxy pour que les
événements circulent de bout en bout :
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;}Ce que le modèle voit et ne voit pas
La couche ask envoie au modèle uniquement :
- L’
AiSchemadu cube actif — JSON sérialisé des mesures, dimensions, hiérarchies, niveaux et membres d’exemple. - Le JSON Schema d’
AiQueryRequestcommeinput_schemade l’outil de sortie structurée. - La question de l’utilisateur et l’historique de conversation que l’appelant a joint.
Le modèle est contraint via tool_choice d’appeler l’outil emit_query
avec une forme AiQueryRequest valide. Les réponses en prose brute sont
rejetées comme dégradées.
Il ne voit jamais :
- Les autres cubes auxquels l’utilisateur a accès — uniquement celui nommé dans la requête.
- Le SQL sous-jacent ni les identifiants de l’entrepôt.
- L’historique de conversation d’autres utilisateurs.
- La requête HTTP, les cookies de session, ni aucun en-tête envoyé par l’appelant.
C’est le même modèle d’isolation qu’utilisent le serveur MCP et l’API AI Query typée, appliqué une couche plus tôt.
Points d’entrée compagnons
Le point d’entrée ask côtoie quelques utilitaires typés sur la même
surface /rest/saiku/api/ai/*. Les agents s’en servent pour résoudre
des noms avant de demander, lancer une simulation, ou aider un opérateur
à verrouiller la gouvernance.
GET /ai/members/search — résoudre un nom de membre
Avant de référencer un membre dans une requête ou un filtre, retrouvez son nom unique exact via une recherche de sous-chaîne insensible à la casse. Miroir de la recherche de valeurs côté OSSIE.
| Paramètre | Requis | Notes |
|---|---|---|
cubeId | oui | connection/catalog/schema/cube |
dimension | oui | Nom de la dimension |
hierarchy | non | Nom de la hiérarchie (par défaut celle de la dimension) |
level | oui | Niveau dans lequel chercher |
q | non | Chaîne de recherche ; omettez-la pour paginer les premiers membres |
limit | non | Nombre max de résultats (par défaut 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 — simulation avec write-back
Fixez la mesure d’un membre à une valeur cible, réexécutez la requête
dans un scénario Mondrian neuf, et obtenez réel vs what-if pour
chaque frère et chaque total pendant que le moteur redistribue l’écart.
Le cube doit déclarer
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 et member sont des noms uniques MDX ; value est la nouvelle
valeur absolue de la mesure pour member ; policy vaut
EQUAL_ALLOCATION par défaut.
GET /ai/schema/{cubeId}/pii-suggestions — aide à la gouvernance
Réservé aux admins. Scanne le cube décrit à la recherche de colonnes qui
correspondent à un motif de PII mais ne sont pas encore annotées
pii=true, pour qu’un opérateur puisse verrouiller le caviardage des
PII sans grepper les logs. Délibérément séparé de la
vue schema destinée aux agents — les agents ne voient jamais la
politique en brouillon de l’opérateur. Renvoie une liste vide (pas un
404) pour un cube qui n’a pas encore été décrit.
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 — flux rédigés par l’administrateur
Les skills sont des fichiers markdown à frontmatter YAML sous
saiku-home/skills/ que n’importe quel tour /ai/ask peut invoquer par
son nom (/weekly-rollup for Q4) ou par correspondance en langage
naturel. Référence complète dans Agent Skills.
Agent Spaces — asks cadrés par persona
Les spaces sont des personas nommées, rédigées par l’administrateur
(« Sales Analyst », « Finance Ops »), qui cadrent toute une surface
d’ask — prompt système, liste blanche de cubes, liste blanche de skills,
prompts suggérés. POST /ai/spaces/{id}/ask utilise la même enveloppe
que ce point d’entrée, avec l’application du cadrage côté serveur en
plus. Référence complète dans Agent Spaces.
Où aller ensuite
- Agent Skills — des flux markdown rédigés par
l’administrateur, découvrables depuis chaque tour
/ai/ask. - Agent Spaces — des personas qui épinglent la liste blanche de cubes, filtrent le catalogue de skills et injectent un prompt système.
- Agent evals — harnais de vérité terrain en YAML pour attraper les régressions d’AI ask quand le fournisseur LLM, le modèle ou le prompt changent.
- AI Query API — la surface typée vers laquelle
/ai/asktraduit. Utile quand vous voulez qu’un agent (et non un humain) rédige la requête. - Serveur MCP — la même surface typée exposée en outils MCP pour les agents Claude Desktop / Cursor / Cline.
- Authentification — jetons Bearer, limites de débit, formes d’erreur.