Zum Inhalt springen

AI Ask API

Die AI Ask API nimmt eine Frage in einfacher Sprache, lässt den konfigurierten LLM-Provider eine typisierte Abfrage gegen das lebende Cube-Schema ausfüllen, schickt diese Abfrage durch denselben Konverter, den die typisierte AI Query API verwendet, und gibt das ausgeführte Ergebnis + das erzeugte MDX + die strukturierte Anfrage zurück, die das Modell emittiert hat.

Es ist die Natural-Language-Schicht, die auf der typisierten Agenten-Oberfläche sitzt. Wo die typisierte API davon ausgeht, dass der Aufrufer AiQueryRequest spricht, lässt die Ask-API einen Menschen „zeig mir den Umsatz nach Land im letzten Quartal” sagen und liefert einen vollständig ausgeführten Cellset zurück, mit der Übersetzung des Modells daneben sichtbar.

Das treibt das AI-Query-Drawer im Workspace an — die ⚡-Schaltfläche in der Symbolleiste öffnet ein Chat-Panel, in dem Benutzer Fragen tippen und auf In Canvas bearbeiten klicken, um das Ergebnis in den aktiven Abfrage-Tab zu legen.

Wann ist sie zu verwenden?

Die Ask-API ist die richtige Oberfläche, wenn:

  • Endbenutzer Fragen tippen werden — die typisierte AI Query API erwartet einen Agenten, der das Cube-Schema bereits kennt; die Ask-API verbirgt diesen Schritt hinter einem LLM.
  • Sie einen Round-Trip pro Frage wollen — /ai/ask erledigt Übersetzung + Ausführung + Envelope-Formung in einem einzigen Aufruf, sodass der Client nicht zwei APIs verketten muss.
  • Sie eine Chat-artige Oberfläche einbetten — das mehrstufige history-Feld lässt Folgefragen gegen frühere Runden auflösen.

Wann sie nicht zu verwenden ist:

  • Agenten auf dem MCP-Server — Agenten bevorzugen die typisierte Oberfläche, weil sie ohnehin gut darin sind, strukturierte Felder aus einem JSON Schema zu füllen. Die Ask-Schicht ist für Menschen.
  • Cubes aus einem Beispiel-Warehouse verfassen — nutzen Sie die AI Inference API, die für den Design-Time-Fluss gedacht ist.

Aktivierung

Zwei Properties + eine Env-Variable pro Provider. Beides lässt sich auf der JVM setzen oder in der Properties-Datei des Deployments, die Spring liest.

# 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

Provider-Defaults:

ProviderDefault-ModellEndpunkt
anthropicclaude-sonnet-4-6https://api.anthropic.com/v1/messages
openaigpt-4o-minihttps://api.openai.com/v1/chat/completions
azure-openai(kein Default)(kein Default — verweigert die Konstruktion ohne explizite Deployment-URL)

Docker

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

Nutzen Sie ein Secret für den Key, eine ConfigMap für den Provider-Namen:

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 — bringen Sie Ihr eigenes Modell mit (saiku#1431)

Enterprise-Deployments können Prompts oft nicht direkt an Anthropic oder OpenAI schicken — das LLM muss innerhalb der VPC des Kunden oder hinter dessen bestehendem Einkauf laufen. Die Ask-Schicht deckt die drei häufigsten BYOLLM-Formen ab, ohne schwere Abhängigkeiten in Saiku zu backen.

FormProviderEndpunkt-FormatAuth-Header
Azure OpenAI Serviceazure-openaihttps://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=<v>api-key: <key>
Self-hosted / OpenAI-kompatibler Proxy (vLLM, Ollama, LiteLLM, Together, Groq)openaijede URL, die OpenAIs Chat-Completions-API sprichtAuthorization: Bearer <key>
AWS Bedrock über LiteLLM davoropenaiLiteLLM vor Bedrock (https://litellm.internal/v1/chat/completions)Authorization: Bearer <litellm-key>

Der native azure-openai-Adapter kümmert sich um die beiden Azure-spezifischen Dinge (Deployment-Name in der URL und api-key-Header), sodass Operatoren für den häufigsten Fall keinen Übersetzungs-Proxy betreiben müssen.

Azure-OpenAI-Aktivierung

  1. Deployen Sie ein OpenAI-kompatibles Modell in Ihre Azure-OpenAI-Ressource. Notieren Sie Ressourcen- und Deployment-Namen.

  2. Holen Sie einen Key aus dem Azure Portal → Ihre Ressource → Keys and Endpoint.

  3. Setzen Sie auf dem 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. Booten Sie den Launcher. Eine INFO-Zeile beim Start bestätigt die Verdrahtung:

    INFO o.s.s.o.a.a.NlAskProviderFactory - AI ask provider: azure-openai (deployment/model=my-deployment, endpoint=https://…)

AWS Bedrock über LiteLLM

Das empfohlene Muster für Bedrock ist, LiteLLM als OpenAI-kompatible Front zu betreiben und Saikus vorhandenen openai-Provider auf LiteLLM zu richten. LiteLLM erledigt die SigV4-Signierung stromaufwärts, sodass Saiku das AWS SDK nicht im Classpath braucht.

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-Fenster
litellm --config litellm-config.yaml --port 4000

Und dann auf der Saiku-Seite:

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>

Derselbe Trick funktioniert für jedes Bedrock-Modell (Titan, Cohere, Mistral, Llama) sowie für GCP Vertex AI, Databricks Model Serving und jeden anderen Provider, den LiteLLM abdeckt.

Selbst gehostete Modelle

Jeder Host, der OpenAIs Chat-Completions-API spricht, ist ein Drop-in-Ersatz. Die gängigen:

  • vLLM — selbst gehostete GPU-Inferenz; OpenAI-kompatibel ab Werk.
  • Ollama — lokale Entwicklung; aktivieren Sie den OpenAI-Kompatibilitätsadapter mit OLLAMA_HOST=0.0.0.0.
  • Together und Groq — SaaS-OpenAI-kompatible Endpunkte für Self-Service-Modell-Hosting.
  • LiteLLM — Proxy, der alles (Bedrock, Vertex, Azure, Anthropic, Hunderte weitere) als OpenAI-kompatibel vorblendet.
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>

Der Endpunkt

POST /saiku/api/ai/ask

Anfrage

{
"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"
}

Nur question und cube sind erforderlich.

history — frühere (user, assistant)-Runden, die an das Modell zurückgesendet werden, sodass Folgefragen wie „jetzt nach Region aufschlüsseln” gegen die frühere Frage aufgelöst werden. System-Prompts werden vom Server kontrolliert; Aufrufer können sie nicht einschleusen.

cellsetDigest — ein Markdown-Digest des Ergebnisses, das der Benutzer gerade ansieht. Dieses Feld zählt mehr, als es aussieht:

forceTool — die Runde auf eine Intent festnageln, statt das Modell wählen zu lassen. query, insight, view_change oder dashboard; lassen Sie es weg (oder senden auto), damit das Modell routet. Das Workspace-Drawer bietet das als Auswahl Auto / Query / Insight / View an.

dashboard ist die Ausnahme: Es ist nie Teil von auto und nur erreichbar, wenn man es ausdrücklich anfordert.

Antwort

Die Antwort trägt bei Erfolg genau eine Intent. Welche, hängt davon ab, wie das Modell die Runde geroutet hat — verzweigen Sie also auf Anwesenheit und nehmen Sie nicht an, dass request immer da ist:

FeldVorhanden, wennEnthält
request + response + queryModelDas Modell mit einer Query geantwortet hatDie typisierte Anfrage, das ausgeführte Ergebnis und das strukturierte Query-Modell
insightDas Modell mit einer Insight geantwortet hatMarkdown-Analyse des Cellsets, den Sie gesendet haben
viewChangeDas Modell mit einem View Change geantwortet hatEin Ziel-View-Modus + Diagrammtyp
emailDraftDas Modell eine E-Mail verfasst hat — und Mail konfiguriert istEin Entwurfstext. Nur Entwurf; das Senden läuft über den normalen E-Mail-Endpunkt, nie über diesen

Dazu bei jeder Antwort: degraded, model und reason, wenn etwas schiefging.

{
"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 ist die strukturierte Abfrage, die das Modell erzeugt hat. Übergeben Sie sie wortwörtlich an POST /ai/query, um sie erneut auszuführen, oder zeigen Sie sie dem Benutzer als „die typisierte Abfrage hinter Ihrer Frage” an.

response ist das ausgeführte Ergebnis, gleiche Form wie die typisierte AI Query API zurückgibt. Wenn das Modell eine Anfrage erzeugt hat, die das Schema ablehnt, ist response.status gleich VALIDATION_ERROR und der Body enthält field + available-Kandidaten — das Workspace-Drawer rendert diese als anklickbare Chips, damit der Benutzer selbst korrigieren kann.

queryModel ist dasselbe strukturierte Modell, das die Chips der Werkbank manipulieren. Es ist das, was In Canvas bearbeiten eine Abfrage zurückgeben lässt, an der der Benutzer weiterziehen kann, statt einer Wand aus MDX, an der er es nicht kann. Fehlt auf degraded Pfaden und dort, wo die Konvertierung scheiterte, bevor eines entstand.

generatedMdx ist ein bequemer Spiegel von response.metadata.generatedMdx.

Statuscodes

HTTPWann
200Übersetzung erfolgreich; response enthält das ausgeführte Ergebnis (oder VALIDATION_ERROR zur Selbstkorrektur).
200 + degraded:trueÜbersetzung in der Provider-Schicht fehlgeschlagen — Transportfehler, Modell hat abgelehnt oder Parse-Fehler. reason enthält die Erklärung.
400Fehlendes question oder cube im Body.
503 + degraded:trueProvider ist noop (nicht konfiguriert) — reason erklärt, wie aktiviert wird.

Beispiele

Standardmäßig aus — klare Rückmeldung

Terminal-Fenster
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..."
# }

Happy Path — vollständiger Round-Trip

Terminal-Fenster
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
# }

Folgefrage — mehrstufig

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

Das Modell sieht die vorherige Runde und löst „nach Quartal” so auf, dass es auch gegen Land gekreuzt wird — gleiche Form wie die erste Antwort mit einer zusätzlichen Hierarchie.

Streaming-Variante — POST /ai/ask/stream (saiku#1433)

Begleitender Endpunkt, der Server-Sent Events spricht, damit eingebettete Chat-Oberflächen Fortschritt rendern können, während er eintrifft, statt auf den vollen Round-Trip zu blockieren. Gleicher Request-Body, gleiche Auth, gleiche Rate-Limits, gleiche Envelope-Form — die Antwort ist ein Strom typisierter Events statt eines einzelnen JSON-Blobs.

Event-Schema

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."}}
EventWannPayload
modelFeuert immer zuerst, wenn der Provider eine Modell-ID zurückgab{"model": "<id>"}
intentNach dem Tool-Routing, vor dem Payload{"kind": "QUERY" | "INSIGHT" | "VIEW_CHANGE"}
chunkNull- oder mehrmals bei prosatragenden Intents (INSIGHT, VIEW_CHANGE.reason){"delta": "<Chunk an Wortgrenze>"} — Deltas zu verketten ist verlustfrei
finalFeuert bei Erfolg immer zuletztVollständiger AskResponse-Envelope — gleiche Form wie synchrones /ai/ask
errorTransport-/Parse-/Auth-Fehler des Providers{"reason": "<Erklärung>"} — gefolgt von einem final mit degraded:true

Client-Beispiele

EventSource kann nur GET, POST-Bodies laufen also über fetch + manuelles Event-Parsing:

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

Setzen Sie X-Accel-Buffering: no (Saiku sendet das bereits) und deaktivieren Sie die Proxy-Pufferung auf Ihrem Reverse Proxy, damit Events Ende zu Ende durchgereicht werden:

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;
}

Was das Modell sieht vs. nicht sieht

Die Ask-Schicht sendet dem Modell nur:

  • Das AiSchema des aktiven Cubes — serialisiertes JSON der Measures, Dimensionen, Hierarchien, Levels und Sample-Member.
  • Das JSON Schema von AiQueryRequest als input_schema des Structured-Output-Tools.
  • Die Frage des Benutzers und etwaige Konversationshistorie, die der Aufrufer angehängt hat.

Das Modell wird über tool_choice gezwungen, das emit_query-Tool mit einer gültigen AiQueryRequest-Form aufzurufen. Rohe Prosa-Antworten werden als degraded abgelehnt.

Es sieht niemals:

  • Andere Cubes, auf die der Benutzer zugreifen kann — nur den in der Anfrage genannten.
  • Das zugrundeliegende SQL oder die Warehouse-Anmeldedaten.
  • Konversationshistorien anderer Benutzer.
  • Die HTTP-Anfrage, Session-Cookies oder irgendeinen Header, den der Aufrufer gesendet hat.

Dies ist dasselbe Isolationsmodell, das der MCP-Server und die typisierte AI Query API verwenden, nur eine Schicht früher angewendet.

Begleitende Endpunkte

Der Ask-Endpunkt steht neben ein paar typisierten Helfern auf derselben /rest/saiku/api/ai/*-Oberfläche. Agenten nutzen sie, um Namen aufzulösen, bevor sie fragen, eine Simulation zu fahren oder einem Operator beim Absichern der Governance zu helfen.

GET /ai/members/search — einen Member-Namen auflösen

Bevor Sie einen Member in einer Abfrage oder einem Filter referenzieren, schlagen Sie seinen exakten Unique Name mit einer Groß-/Kleinschreibung-ignorierenden Teilstring-Suche nach. Spiegelt die Werte-Suche auf der OSSIE-Seite.

Query-ParameterPflichtAnmerkungen
cubeIdjaconnection/catalog/schema/cube
dimensionjaDimensionsname
hierarchyneinHierarchiename (Default ist die Default-Hierarchie der Dimension)
leveljaLevel, in dem gesucht wird
qneinSuchstring; weglassen, um die ersten Member zu blättern
limitneinMax. Treffer (Default 20)
Terminal-Fenster
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 — Write-back-Simulation

Setzen Sie die Measure eines Members auf einen Zielwert, führen Sie die Abfrage in einem frischen Mondrian-Szenario erneut aus und erhalten Sie Ist vs. Was-wäre-wenn für jedes Geschwister und jede Summe, während die Engine das Delta neu verteilt. Der Cube muss enableScenarios="true" deklarieren.

Terminal-Fenster
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 und member sind MDX-Unique-Names; value ist der neue absolute Measure-Wert für member; policy ist standardmäßig EQUAL_ALLOCATION.

GET /ai/schema/{cubeId}/pii-suggestions — Governance-Helfer

Nur für Admins. Scannt den beschriebenen Cube nach Spalten, die einem PII-Muster entsprechen, aber noch nicht mit pii=true annotiert sind, damit ein Operator die PII-Redaction absichern kann, ohne Logs zu greppen. Bewusst getrennt von der agentenseitigen Schema-Sicht — Agenten sehen nie den Policy-Entwurf des Operators. Gibt für einen noch nicht beschriebenen Cube eine leere Liste zurück (kein 404).

Terminal-Fenster
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 — vom Admin verfasste Workflows

Skills sind Markdown-Dateien mit YAML-Frontmatter unter saiku-home/skills/, die jede /ai/ask-Runde per Namen (/weekly-rollup for Q4) oder per Natural-Language-Treffer aufrufen kann. Vollständige Referenz in Agent Skills.

Agent Spaces — persona-gescopte Asks

Spaces sind benannte, vom Admin verfasste Personas („Sales Analyst”, „Finance Ops”), die eine ganze Ask-Oberfläche scopen — System-Prompt, Cube-Allowlist, Skill-Allowlist, Vorschlags-Prompts. POST /ai/spaces/{id}/ask nutzt denselben Envelope wie dieser Endpunkt, mit serverseitiger Scope-Durchsetzung obendrauf. Vollständige Referenz in Agent Spaces.

Wie geht es weiter?

  • Agent Skills — vom Admin verfasste Markdown-Workflows, die aus jeder /ai/ask-Runde auffindbar sind.
  • Agent Spaces — Personas, die die Cube-Allowlist festnageln, den Skill-Katalog filtern und einen System-Prompt injizieren.
  • Agent-Evals — YAML-Ground-Truth-Harness, um AI-Ask-Regressionen zu fangen, wenn sich LLM-Provider, Modell oder Prompt ändern.
  • AI Query API — die typisierte Oberfläche, in die /ai/ask übersetzt. Nützlich, wenn ein Agent (kein Mensch) die Anfrage erstellen soll.
  • MCP-Server — dieselbe typisierte Oberfläche als MCP-Tools für Claude Desktop / Cursor / Cline Agenten.
  • Authentifizierung — Bearer-Tokens, Rate-Limits, Fehlerformate.