AI Ask API
AI Ask API bierze pytanie zadane zwykłym językiem, prosi skonfigurowanego dostawcę LLM o wypełnienie typowanego zapytania wobec żywej schemy kostki, przepuszcza to zapytanie przez ten sam konwerter, którego używa typowane AI Query API, i zwraca wykonany wynik + wygenerowany MDX + strukturalne żądanie, które wyemitował model.
To warstwa języka naturalnego siedząca na typowanej powierzchni dla
agentów. Tam, gdzie typowane API zakłada, że wołający mówi
AiQueryRequest, ask API pozwala człowiekowi powiedzieć „pokaż
sprzedaż wedle kraju w zeszłym kwartale” i dostać w pełni wykonany
cellset, z widoczną obok translacją modelu.
To napędza szufladę AI Query w workspace — przycisk ⚡ na pasku narzędzi otwiera panel czatu, w którym użytkownicy wpisują pytania i klikają Edytuj na kanwie, by upuścić wynik w aktywnej karcie zapytania.
Kiedy jej używać
Ask API jest właściwą powierzchnią, gdy:
- Użytkownicy końcowi będą wpisywać pytania — typowane AI Query API oczekuje agenta, który już zna schemę kostki; ask API chowa ten krok za LLM-em.
- Chcesz jeden round-trip na pytanie —
/ai/askrobi translację + wykonanie + uformowanie koperty w jednym wywołaniu, więc klient nie musi łączyć dwóch API. - Osadzasz powierzchnię w stylu czatu — wielorundowe pole
historypozwala pytaniom uzupełniającym rozwiązywać się wobec wcześniejszych rund.
Kiedy nie jej używać:
- Agenci na serwerze MCP — agenci wolą typowaną powierzchnię, bo i tak są dobrzy w wypełnianiu strukturalnych pól z JSON Schema. Warstwa ask jest dla ludzi.
- Tworzenie kostek z przykładowej hurtowni — użyj AI Inference API, zaprojektowanego pod przepływ projektowy.
Aktywacja
Dwie property + jedna zmienna środowiskowa na dostawcę. Oba da się ustawić na JVM albo w pliku properties wdrożenia, który czyta 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_SECONDSDomyślne ustawienia dostawców:
| Dostawca | Model domyślny | 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 | (brak domyślnego) | (brak domyślnego — odmawia konstrukcji bez jawnego URL-a deploymentu) |
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
Użyj Secret na klucz i ConfigMap na nazwę dostawcy:
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 — przynieś własny model (saiku#1431)
Wdrożenia enterprise często nie mogą wysyłać promptów wprost do Anthropica ani OpenAI — LLM musi chodzić wewnątrz VPC klienta albo za jego istniejącym zakupem. Warstwa ask pokrywa trzy najczęstsze kształty BYOLLM, nie wpiekając w Saiku ciężkich zależności.
| Kształt | Dostawca | Format endpointu | Nagłówek auth |
|---|---|---|---|
| Azure OpenAI Service | azure-openai | https://<resource>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=<v> | api-key: <key> |
| Self-hosted / proxy zgodny z OpenAI (vLLM, Ollama, LiteLLM, Together, Groq) | openai | dowolny URL mówiący Chat Completions API OpenAI | Authorization: Bearer <key> |
| AWS Bedrock przez LiteLLM z przodu | openai | LiteLLM przed Bedrockiem (https://litellm.internal/v1/chat/completions) | Authorization: Bearer <litellm-key> |
Natywny adapter azure-openai załatwia dwie rzeczy specyficzne dla
Azure (nazwa deploymentu w URL-u i nagłówek api-key), żeby operatorzy
nie musieli w najczęstszym przypadku stawiać proxy tłumaczącego.
Aktywacja Azure OpenAI
-
Wdróż model zgodny z OpenAI w swoim zasobie Azure OpenAI. Zanotuj nazwę zasobu i nazwę deploymentu.
-
Wyciągnij klucz z Azure Portal → Twój zasób → Keys and Endpoint.
-
Ustaw na launcherze:
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> -
Uruchom launcher. Linia INFO przy starcie potwierdza podpięcie:
INFO o.s.s.o.a.a.NlAskProviderFactory - AI ask provider: azure-openai (deployment/model=my-deployment, endpoint=https://…)
AWS Bedrock przez LiteLLM
Zalecany wzorzec dla Bedrocka to uruchomić
LiteLLM jako front zgodny z OpenAI
i skierować istniejącego w Saiku dostawcę openai na LiteLLM. LiteLLM
załatwia podpisywanie SigV4 w górę strumienia, więc Saiku nie potrzebuje
AWS SDK na classpathie.
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 4000A potem po stronie 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>Ta sama sztuczka działa dla każdego modelu Bedrocka (Titan, Cohere, Mistral, Llama) oraz dla GCP Vertex AI, Databricks Model Serving i każdego innego dostawcy, którego pokrywa LiteLLM.
Modele hostowane u siebie
Każdy host, który mówi Chat Completions API OpenAI, wchodzi bez zmian. Te popularne:
- vLLM — własna inferencja na GPU; zgodność z OpenAI od ręki.
- Ollama — lokalny development; włącz adapter zgodności z OpenAI
przez
OLLAMA_HOST=0.0.0.0. - Together i Groq — SaaS-owe endpointy zgodne z OpenAI do samoobsługowego hostowania modeli.
- LiteLLM — proxy, które wystawia cokolwiek (Bedrock, Vertex, Azure, Anthropic, setki innych) jako zgodne z 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>Endpoint
POST /saiku/api/ai/askŻądanie
{ "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"}Wymagane są tylko question i cube.
history — wcześniejsze rundy (user, assistant), odsyłane do
modelu, żeby dopytania w rodzaju „teraz rozbij to wedle regionu”
rozwiązywały się wobec wcześniejszego pytania. Prompty systemowe
kontroluje serwer; wołający nie mogą ich wstrzyknąć.
cellsetDigest — markdownowy skrót wyniku, na który użytkownik
właśnie patrzy. To pole waży więcej, niż wygląda:
forceTool — przypnij rundę do jednej intencji, zamiast pozwalać
modelowi wybierać. query, insight, view_change albo dashboard;
pomiń je (albo wyślij auto), by model routował. Szuflada workspace
wystawia to jako wybór Auto / Query / Insight / View.
dashboard jest wyjątkiem: nigdy nie jest częścią auto i da się go
osiągnąć wyłącznie prosząc o niego wprost.
Odpowiedź
Odpowiedź przy powodzeniu niesie dokładnie jedną intencję. Którą —
zależy od tego, jak model zroutował rundę, więc rozgałęziaj się po
obecności, a nie zakładaj, że request jest zawsze:
| Pole | Obecne, gdy | Niesie |
|---|---|---|
request + response + queryModel | Model odpowiedział zapytaniem | Typowane żądanie, wykonany wynik i strukturalny model zapytania |
insight | Model odpowiedział wglądem | Markdownową analizę cellsetu, który wysłałeś |
viewChange | Model odpowiedział zmianą widoku | Docelowy tryb widoku + typ wykresu |
emailDraft | Model ułożył e-mail — i poczta jest skonfigurowana | Treść szkicu. Tylko szkic; wysyłka idzie przez normalny endpoint pocztowy, nigdy przez ten |
Do tego przy każdej odpowiedzi: degraded, model oraz reason, gdy
coś poszło źle.
{ "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 to strukturalne zapytanie, które wyprodukował model. Podaj je
dosłownie do POST /ai/query, by je wykonać
ponownie, albo pokaż użytkownikowi jako „typowane zapytanie stojące za
Twoim pytaniem”.
response to wykonany wynik, w tym samym kształcie, jaki zwraca
typowane AI Query API. Jeśli model wyemitował żądanie, które schema
odrzuca, response.status to VALIDATION_ERROR, a ciało niesie field
- kandydatów
available— szuflada workspace renderuje je jako klikalne chipy, żeby użytkownik mógł się poprawić sam.
queryModel to ten sam strukturalny model, którym manipulują chipy
warsztatu. To on sprawia, że Edytuj na kanwie oddaje zapytanie,
które użytkownik może dalej przeciągać, a nie ścianę MDX-a, przy której
nic nie zrobi. Nieobecne na ścieżkach degraded i tam, gdzie konwersja
padła, zanim je wytworzyła.
generatedMdx to wygodne lustro
response.metadata.generatedMdx.
Kody statusu
| HTTP | Kiedy |
|---|---|
200 | Translacja się powiodła; response niesie wykonany wynik (albo VALIDATION_ERROR do samodzielnej poprawy). |
200 + degraded:true | Translacja padła w warstwie dostawcy — błąd transportu, model odmówił albo błąd parsowania. reason niesie wyjaśnienie. |
400 | Brak question albo cube w ciele. |
503 + degraded:true | Dostawca to noop (nieskonfigurowany) — reason wyjaśnia, jak włączyć. |
Przykłady
Domyślnie wyłączone — czytelna informacja zwrotna
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..."# }Ścieżka szczęśliwa — pełny round-trip
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# }Dopytanie — wielorundowo
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."} ]}EOFModel widzi poprzednią rundę i rozwiązuje „wedle kwartału” jako skrzyżowane także z krajem — ten sam kształt co pierwsza odpowiedź z jedną dodatkową hierarchią.
Wariant strumieniowy — POST /ai/ask/stream (saiku#1433)
Towarzyszący endpoint mówiący Server-Sent Events, żeby osadzone powierzchnie czatu mogły renderować postęp w miarę jego napływania, zamiast blokować się na pełnym round-tripie. To samo ciało żądania, ta sama auth, te same limity, ten sam kształt koperty — odpowiedzią jest strumień typowanych zdarzeń zamiast jednego bloba JSON.
Schemat zdarzeń
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."}}| Zdarzenie | Kiedy | Ładunek |
|---|---|---|
model | Zawsze odpala się pierwsze, gdy dostawca zwrócił id modelu | {"model": "<id>"} |
intent | Po zroutowaniu narzędzia, przed ładunkiem | {"kind": "QUERY" | "INSIGHT" | "VIEW_CHANGE"} |
chunk | Zero lub więcej razy dla intencji niosących prozę (INSIGHT, VIEW_CHANGE.reason) | {"delta": "<kawałek na granicy słowa>"} — sklejanie delt jest bezstratne |
final | Przy powodzeniu zawsze odpala się ostatnie | Pełna koperta AskResponse — ten sam kształt co synchroniczne /ai/ask |
error | Błąd transportu / parsowania / auth dostawcy | {"reason": "<wyjaśnienie>"} — po nim final z degraded:true |
Przykłady klienta
EventSource umie tylko GET, więc ciała POST idą przez fetch
i ręczne parsowanie zdarzeń:
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 };}Zadziała każdy klient SSE — ten endpoint zwraca strumień typowanych
zdarzeń, a nie kawałki w smaku Vercela, których AI SDK oczekuje
natywnie, więc napisałbyś mały adapter tłumaczący nasze zdarzenia
chunk na to, co konsumuje Twoja warstwa renderująca.
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; }}Przydatne do lokalnego debugowania:
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":{...}}'-N wyłącza buforowanie curla, żeby zdarzenia wychodziły w miarę
napływania.
Nginx / reverse proxy
Ustaw X-Accel-Buffering: no (Saiku już to wysyła) i wyłącz buforowanie
proxy na swoim reverse proxy, żeby zdarzenia przechodziły od końca do
końca:
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;}Co model widzi, a czego nie
Warstwa ask wysyła modelowi wyłącznie:
AiSchemaaktywnej kostki — zserializowany JSON miar, wymiarów, hierarchii, poziomów i przykładowych memberów.- JSON Schema
AiQueryRequestjakoinput_schemanarzędzia wyjścia strukturalnego. - Pytanie użytkownika i historię konwersacji, którą dołączył wołający.
Model jest przez tool_choice zmuszony do wywołania narzędzia
emit_query z prawidłowym kształtem AiQueryRequest. Surowe odpowiedzi
prozą są odrzucane jako degraded.
Nigdy nie widzi:
- Innych kostek, do których użytkownik ma dostęp — tylko tę wskazaną w żądaniu.
- Leżącego pod spodem SQL-a ani poświadczeń hurtowni.
- Historii konwersacji innych użytkowników.
- Żądania HTTP, ciasteczek sesji ani żadnego nagłówka wysłanego przez wołającego.
To ten sam model izolacji, którego używają serwer MCP i typowane AI Query API, zastosowany o warstwę wcześniej.
Towarzyszące endpointy
Endpoint ask stoi obok kilku typowanych pomocników na tej samej
powierzchni /rest/saiku/api/ai/*. Agenci używają ich, by rozwiązać
nazwy przed zapytaniem, uruchomić symulację albo pomóc operatorowi
domknąć governance.
GET /ai/members/search — rozwiązanie nazwy membera
Zanim odwołasz się do membera w zapytaniu albo filtrze, znajdź jego dokładny unique name wyszukiwaniem podciągu ignorującym wielkość liter. Odbicie wyszukiwania wartości po stronie OSSIE.
| Parametr | Wymagany | Uwagi |
|---|---|---|
cubeId | tak | connection/catalog/schema/cube |
dimension | tak | Nazwa wymiaru |
hierarchy | nie | Nazwa hierarchii (domyślnie domyślna hierarchia wymiaru) |
level | tak | Poziom, w którym szukamy |
q | nie | Szukany ciąg; pomiń, by przewijać pierwszych memberów |
limit | nie | Maks. trafień (domyślnie 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 — symulacja z zapisem zwrotnym
Ustaw miarę jednego membera na wartość docelową, przelicz zapytanie
w świeżym scenariuszu Mondriana i dostań rzeczywiste kontra
co-gdyby dla każdego rodzeństwa i sumy, gdy silnik na nowo rozdziela
deltę. Kostka musi deklarować
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 i member to unique name’y MDX; value to nowa bezwzględna
wartość miary dla member; policy domyślnie to EQUAL_ALLOCATION.
GET /ai/schema/{cubeId}/pii-suggestions — pomocnik governance
Tylko dla adminów. Skanuje opisaną kostkę w poszukiwaniu kolumn, które
pasują do wzorca PII, ale nie są jeszcze oznaczone pii=true, żeby
operator mógł domknąć redakcję PII bez greppowania
logów. Celowo oddzielone od widoku schemy dla agentów — agenci nigdy nie
widzą roboczej polityki operatora. Dla kostki jeszcze nieopisanej
zwraca pustą listę (a nie 404).
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" }, … ] }Skille — workflow pisane przez administratora
Skille to pliki markdown z frontmatterem YAML pod
saiku-home/skills/, które każda runda /ai/ask może wywołać po nazwie
(/weekly-rollup for Q4) albo przez dopasowanie w języku naturalnym.
Pełna referencja w Agent Skills.
Agent Spaces — zapytania zakresowane personą
Spaces to nazwane, pisane przez administratora persony („Sales
Analyst”, „Finance Ops”), które zakresują całą powierzchnię ask —
prompt systemowy, lista dozwolonych kostek, lista dozwolonych skilli,
sugerowane prompty. POST /ai/spaces/{id}/ask używa tej samej koperty
co ten endpoint, z serwerowym egzekwowaniem zakresu na wierzchu. Pełna
referencja w Agent Spaces.
Dokąd dalej
- Agent Skills — pisane przez administratora
workflow w markdownie, odkrywalne z każdej rundy
/ai/ask. - Agent Spaces — persony przypinające listę dozwolonych kostek, filtrujące katalog skilli i wstrzykujące prompt systemowy.
- Agent evals — YAML-owy harness ground truth do łapania regresji AI ask, gdy zmienia się dostawca LLM, model albo prompt.
- AI Query API — typowana powierzchnia, na którą
/ai/asktłumaczy. Przydatna, gdy chcesz, by żądanie tworzył agent, a nie człowiek. - Serwer MCP — ta sama typowana powierzchnia wystawiona jako narzędzia MCP dla agentów Claude Desktop / Cursor / Cline.
- Uwierzytelnianie — tokeny Bearer, limity żądań, kształty błędów.