Przejdź do głównej zawartości

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/ask robi translację + wykonanie + uformowanie koperty w jednym wywołaniu, więc klient nie musi łączyć dwóch API.
  • Osadzasz powierzchnię w stylu czatu — wielorundowe pole history pozwala 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 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

Domyślne ustawienia dostawców:

DostawcaModel domyślnyEndpoint
anthropicclaude-sonnet-4-6https://api.anthropic.com/v1/messages
openaigpt-4o-minihttps://api.openai.com/v1/chat/completions
azure-openai(brak domyślnego)(brak domyślnego — odmawia konstrukcji bez jawnego URL-a deploymentu)

Docker

Okno terminala
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

Użyj Secret na klucz i ConfigMap na nazwę dostawcy:

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 — 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łtDostawcaFormat endpointuNagłówek auth
Azure OpenAI Serviceazure-openaihttps://<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)openaidowolny URL mówiący Chat Completions API OpenAIAuthorization: Bearer <key>
AWS Bedrock przez LiteLLM z przoduopenaiLiteLLM 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

  1. Wdróż model zgodny z OpenAI w swoim zasobie Azure OpenAI. Zanotuj nazwę zasobu i nazwę deploymentu.

  2. Wyciągnij klucz z Azure Portal → Twój zasób → Keys and Endpoint.

  3. Ustaw na launcherze:

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

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

A potem po stronie 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>

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

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:

PoleObecne, gdyNiesie
request + response + queryModelModel odpowiedział zapytaniemTypowane żądanie, wykonany wynik i strukturalny model zapytania
insightModel odpowiedział wglądemMarkdownową analizę cellsetu, który wysłałeś
viewChangeModel odpowiedział zmianą widokuDocelowy tryb widoku + typ wykresu
emailDraftModel ułożył e-mail — i poczta jest skonfigurowanaTreść 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

HTTPKiedy
200Translacja się powiodła; response niesie wykonany wynik (albo VALIDATION_ERROR do samodzielnej poprawy).
200 + degraded:trueTranslacja padła w warstwie dostawcy — błąd transportu, model odmówił albo błąd parsowania. reason niesie wyjaśnienie.
400Brak question albo cube w ciele.
503 + degraded:trueDostawca to noop (nieskonfigurowany) — reason wyjaśnia, jak włączyć.

Przykłady

Domyślnie wyłączone — czytelna informacja zwrotna

Okno terminala
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

Okno terminala
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

Okno terminala
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

Model 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: 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."}}
ZdarzenieKiedyŁadunek
modelZawsze odpala się pierwsze, gdy dostawca zwrócił id modelu{"model": "<id>"}
intentPo zroutowaniu narzędzia, przed ładunkiem{"kind": "QUERY" | "INSIGHT" | "VIEW_CHANGE"}
chunkZero lub więcej razy dla intencji niosących prozę (INSIGHT, VIEW_CHANGE.reason){"delta": "<kawałek na granicy słowa>"} — sklejanie delt jest bezstratne
finalPrzy powodzeniu zawsze odpala się ostatniePełna koperta AskResponse — ten sam kształt co synchroniczne /ai/ask
errorBłą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 };
}

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:

  • AiSchema aktywnej kostki — zserializowany JSON miar, wymiarów, hierarchii, poziomów i przykładowych memberów.
  • JSON Schema AiQueryRequest jako input_schema narzę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.

ParametrWymaganyUwagi
cubeIdtakconnection/catalog/schema/cube
dimensiontakNazwa wymiaru
hierarchynieNazwa hierarchii (domyślnie domyślna hierarchia wymiaru)
leveltakPoziom, w którym szukamy
qnieSzukany ciąg; pomiń, by przewijać pierwszych memberów
limitnieMaks. trafień (domyślnie 20)
Okno terminala
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".

Okno terminala
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).

Okno terminala
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/ask tł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.