Aller au contenu

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/ask fait 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 history permet 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 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

Valeurs par défaut des fournisseurs :

FournisseurModèle par défautPoint d’entrée
anthropicclaude-sonnet-4-6https://api.anthropic.com/v1/messages
openaigpt-4o-minihttps://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

Fenêtre 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

Utilisez un Secret pour la clé, une ConfigMap pour le nom du fournisseur :

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

FormeFournisseurFormat du point d’entréeEn-tête d’auth
Azure OpenAI Serviceazure-openaihttps://<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)openaitoute URL qui parle l’API Chat Completions d’OpenAIAuthorization: Bearer <key>
AWS Bedrock via LiteLLM en façadeopenaiLiteLLM 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

  1. Déployez un modèle compatible OpenAI dans votre ressource Azure OpenAI. Notez le nom de la ressource et celui du déploiement.

  2. Récupérez une clé depuis le portail Azure → votre ressource → Keys and Endpoint.

  3. Définissez sur le 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. 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.

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

Puis, côté 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>

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

Le point d’entrée

POST /saiku/api/ai/ask

Requê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à :

ChampPrésent quandPorte
request + response + queryModelLe modèle a répondu par une requêteLa requête typée, le résultat exécuté, et le modèle de requête structuré
insightLe modèle a répondu par un insightUne analyse markdown du cellset que vous avez envoyé
viewChangeLe modèle a répondu par un changement de vueUn mode de vue cible + un type de graphique
emailDraftLe 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

HTTPQuand
200La traduction a réussi ; response porte le résultat exécuté (ou VALIDATION_ERROR pour que l’utilisateur se corrige).
200 + degraded:trueLa traduction a échoué au niveau du fournisseur — erreur de transport, refus du modèle, ou erreur de parsing. reason porte l’explication.
400question ou cube manquant dans le corps.
503 + degraded:trueLe fournisseur est noop (non configuré) — reason explique comment l’activer.

Exemples

Désactivé par défaut — retour clair

Fenêtre 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..."
# }

Cas nominal — aller-retour complet

Fenêtre 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
# }

Suivi — multi-tours

Fenêtre 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

Le 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: 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."}}
ÉvénementQuandCharge utile
modelSe déclenche toujours en premier quand le fournisseur a renvoyé un id de modèle{"model": "<id>"}
intentAprès le routage d’outil, avant la charge utile{"kind": "QUERY" | "INSIGHT" | "VIEW_CHANGE"}
chunkZé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
finalSe déclenche toujours en dernier en cas de succèsEnveloppe 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 };
}

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’AiSchema du cube actif — JSON sérialisé des mesures, dimensions, hiérarchies, niveaux et membres d’exemple.
  • Le JSON Schema d’AiQueryRequest comme input_schema de 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ètreRequisNotes
cubeIdouiconnection/catalog/schema/cube
dimensionouiNom de la dimension
hierarchynonNom de la hiérarchie (par défaut celle de la dimension)
levelouiNiveau dans lequel chercher
qnonChaîne de recherche ; omettez-la pour paginer les premiers membres
limitnonNombre max de résultats (par défaut 20)
Fenêtre 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 — 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".

Fenêtre 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 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.

Fenêtre 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 — 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/ask traduit. 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.