Użyj Genie One API

Important

Ta funkcja jest dostępna w wersji beta. Administrator przestrzeni roboczej musi włączyć podgląd API Genie One . Zobacz Wymagania.

Interfejs API Genie One pozwala Twojej aplikacji, usłudze backendowej lub agentowi zadawać Genie One pytania w języku naturalnym dotyczące Twoich danych przez HTTP i strumieniować odpowiedzi zwrotnie. Genie One obsługuje wszystkie dane, do których ma dostęp użytkownik wywołujący, i opiera swoje odpowiedzi na Genie Ontology, więc nie musisz najpierw skonfigurować wyselekcjonowanego agenta. Nowe pytania są uruchamiane z uprawnieniami Unity Catalog użytkownika wywołującego, więc odpowiedzi zawierają tylko dane, do których użytkownik wywołujący ma dostęp. Odczytanie zapisanej odpowiedzi lub historii rozmów zwraca zapisaną treść. Nie uruchamia ponownie zapytań ani nie sprawdza uprawnień na danych bazowych.

Ta strona wyjaśnia, jak się uwierzytelniać, zadawać pytania, strumieniować odpowiedzi i zarządzać rozmowami. Pełne formaty żądań i odpowiedzi można znaleźć w referencji Genie One API.

Requirements

  • Administrator obszaru roboczego musi włączyć podgląd Genie One API na stronie Podglądy obszaru roboczego.
  • Dzwoniący musi umieć korzystać z Genie One. Uprawnienie dostępu dla użytkownika lub jakiekolwiek wyższe uprawnienie do przestrzeni roboczej wystarczy. Zobacz Co to jest dostęp konsumentów?.
  • Wywołujący musi mieć uprawnienia SELECT do danych Unity Catalog, które wykorzystują jego pytania.
  • Aby wykonywać zapytania w określonym magazynie SQL, wywołujący musi mieć co najmniej uprawnienie CAN USE do tego magazynu. Jeśli nie określisz magazynu, Genie One wybiera odpowiedni magazyn.

Authenticate

API Genie One akceptuje tokeny dostępu OAuth o zakresie genie.

  • W aplikacjach, w których obecny jest użytkownik, używaj OAuth dla użytkowników (OAuth U2M). Żądania są wykonywane jako ten użytkownik, więc odpowiedzi odzwierciedlają uprawnienia użytkownika do Unity Catalog.
  • Dla zautomatyzowanych zadań używaj service principal z OAuth dla service principals (OAuth M2M). Jednostka usługi musi mieć dostęp do danych i magazynów SQL, z których korzystają jej pytania.

Potrzebujesz też adresu URL swojego workspace. Przykłady na tej stronie używają do tego <workspace-url>. Zobacz Pobieranie identyfikatorów dla obiektów obszaru roboczego.

Zadaj pytanie i przesyłaj odpowiedź na żywo

Wyślij pytanie na adres POST /api/2.0/genie/one/responses. Punkt końcowy zwraca odpowiedź text/event-stream, która przesyła strumieniowo postępy i ostateczną odpowiedź Genie One jako Server-Sent Events (SSE).

Zacznij rozmowę

Pomiń conversation_id, aby rozpocząć nową rozmowę. Ustaw input na pytanie:

curl

curl -N -X POST "https://<workspace-url>/api/2.0/genie/one/responses" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"input": "How did revenue change last quarter?"}'

Opcja -N wyłącza buforowanie wyjścia, dzięki czemu curl drukuje każde zdarzenie w momencie jego wystąpienia.

Python

Poniższy przykład wykorzystuje Databricks SDK dla Python wyłącznie do obsługi uwierzytelniania, więc działa z OAuth U2M, OAuth M2M lub profilem konfiguracyjnym. Wysyła żądanie za pomocą biblioteki requests, przekazuje identyfikatory odpowiedzi i rozmów do funkcji callback on_created zaraz po zaakceptowaniu odpowiedzi, a jeśli stream kończy się wcześniej, wznawia działanie za pomocą żądania GET. Następnie drukuje ostateczną odpowiedź.

Zainstaluj pakiety, których używa ten przykład:

pip install databricks-sdk requests

import json
import time

import requests
from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
base_url = f"{w.config.host}/api/2.0/genie/one"
terminal_events = ("response.completed", "response.failed", "response.incomplete")


def get_response(conversation_id, response_id, timeout_seconds=600):
    # Poll the stored response until it reaches a terminal status.
    deadline = time.time() + timeout_seconds
    while True:
        resp = requests.get(
            f"{base_url}/conversations/{conversation_id}/responses/{response_id}",
            headers=w.config.authenticate(),
        )
        resp.raise_for_status()
        response = resp.json()
        if response["status"] != "in_progress" or time.time() > deadline:
            return response
        time.sleep(3)


def ask(question, conversation_id=None, on_created=None):
    body = {"input": question}
    if conversation_id:
        body["conversation_id"] = conversation_id

    created = None
    try:
        with requests.post(
            f"{base_url}/responses",
            headers={**w.config.authenticate(), "Content-Type": "application/json"},
            json=body,
            stream=True,
        ) as resp:
            resp.raise_for_status()
            # The stream is UTF-8, but its content type doesn't declare a charset.
            resp.encoding = "utf-8"
            for line in resp.iter_lines(decode_unicode=True):
                if not line or not line.startswith("data:"):
                    continue
                # SSE allows an optional single space after "data:".
                data = line[len("data:"):]
                if data.startswith(" "):
                    data = data[1:]
                if data == "[DONE]":
                    break
                event = json.loads(data)
                if event["type"] == "response.created":
                    created = event["response"]
                    if on_created:
                        on_created(created["conversation_id"], created["id"])
                elif event["type"] in terminal_events:
                    return event["response"]
    except requests.RequestException:
        # Without response.created, you can't tell whether the request was accepted.
        if created is None:
            raise
    if created is None:
        raise RuntimeError("The stream ended before the response was accepted.")
    # The stream ended or disconnected before a terminal event. Recover with GET.
    return get_response(created["conversation_id"], created["id"])


response = ask(
    "How did revenue change last quarter?",
    on_created=lambda conversation_id, response_id: print(
        f"conversation_id={conversation_id} response_id={response_id}"
    ),
)
print(response["status"])
for item in response["output"]:
    if item.get("phase") == "final_answer":
        # Keep parts separate so Markdown tables and source notes stay on their own lines.
        print("\n\n".join(part["text"] for part in item["content"]))

Ten przykład czeka na zdarzenie terminalne. Aby pokazać postęp podczas działania Genie One, obsługuj także zdarzenia elementów wyjściowych, jak opisano w Odczytywanie strumienia zdarzeń.

Odczytaj strumień zdarzeń

Każde zdarzenie ma nazwę SSE event oraz ciało JSON data z odpowiadającym type i rosnącym sequence_number. Skrócony strumień wygląda tak:

event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"object":"response","id":"9f7c84c6d3af4ae8ac5cc43590a15366","model":"genie-one","status":"in_progress","output":[],"conversation_id":"6a34b9a50cb4435da7c463130c9d42c1"}}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":1,"output_index":0,"item":{"type":"message","role":"assistant","status":"in_progress","phase":"final_answer","content":[{"type":"output_text","text":"Revenue increased 12% last quarter.","annotations":[]}]}}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":2,"output_index":0,"item":{"type":"message","role":"assistant","status":"completed","phase":"final_answer","content":[{"type":"output_text","text":"Revenue increased 12% last quarter.","annotations":[]}]}}

event: response.completed
data: {"type":"response.completed","sequence_number":3,"response":{"object":"response","id":"9f7c84c6d3af4ae8ac5cc43590a15366","status":"completed","output":[...],"conversation_id":"6a34b9a50cb4435da7c463130c9d42c1"}}

data: [DONE]

Obsługuj zdarzenia w następujący sposób:

  • response.created: Odpowiedź przyjęta. Zapisz response.id i response.conversation_id. Potrzebujesz, żeby zadali pytanie uzupełniające lub poradzili sobie po rozłączeniu strumienia.
  • response.output_item.added, response.output_item.updated, oraz response.output_item.done: Wiadomość asystenta została dodana, zmieniona lub zakończona. Każde zdarzenie niesie pełną wiadomość, więc zamień wiadomość w output_index zamiast dodawać do niej tekst.
  • response.completed, response.failed, lub response.incomplete: Odpowiedź osiągnęła stan końcowy. Tablica response.output zawiera ostatnie wiadomości asystenta. Strumień następnie kończy się elementem data: [DONE].

Każda wiadomość asystenta ma element phase. Wiadomości oznaczone fazą commentary opisują postępy Genie One podczas działania i możesz je wyświetlać jako aktualizacje statusu. Wiadomość z fazą final_answer jest odpowiedzią. Tekst odpowiedzi to Markdown i może zawierać tabele wyników.

Jeśli odpowiedź zakończy się błędem po jej zaakceptowaniu, status HTTP nadal wynosi 200, a strumień kończy się zdarzeniem response.failed. Obiekt response.error opisuje awarię. Zobacz Rozwiązywanie problemów.

Zadaj pytanie uzupełniające

Aby kontynuować rozmowę, przekaż element conversation_id z response.created. Genie One wykorzystuje wcześniejsze pytania i odpowiedzi jako kontekst.

curl -N -X POST "https://<workspace-url>/api/2.0/genie/one/responses" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Break that down by region.",
    "conversation_id": "<conversation-id>"
  }'

Możesz też ustawić warehouse_id tak, aby uruchamiać zapytania w konkretnym magazynie SQL, oraz ustawić user_timezone na strefę czasową IANA, na przykład America/Los_Angeles, aby Genie One interpretował daty względne w strefie czasowej użytkownika.

Odzyskaj połączenie po jego zerwaniu

Rozłączenie się ze strumieniem nie anuluje odpowiedzi. Genie One nadal działa, a wynik można pobrać za pomocą identyfikatorów z response.created:

curl "https://<workspace-url>/api/2.0/genie/one/conversations/<conversation-id>/responses/<response-id>" \
  -H "Authorization: Bearer <access-token>"

Żądanie zwraca ten sam obiekt Response co zdarzenie strumienia końcowego. Gdy status jest in_progress, zapytuj punkt końcowy co kilka sekund. Zatrzymaj się, gdy jest to status, completed, failed lub incomplete.

Nie wysyłaj ponownie żądania POST, aby odzyskać. Każde POST żądanie rozpoczyna nową odpowiedź.

Przeczytaj cytowania

Każda output_text część ma annotations tablicę zawierającą listę źródeł, których Genie One użył do tego tekstu. Każda adnotacja obejmuje:

  • title: Wyświetlana nazwa źródła.
  • asset_type: Rodzaj źródła, taki jak TABLE, NOTEBOOK, lub WEB.
  • identifier: Identyfikator zasobu, ścieżka woluminów lub adres URL internetowy.
  • index: Numer cytowania liczony od 1, do którego odnosi się tekst odpowiedzi.

Zarządzaj rozmowami

Rozmowy tworzone za pomocą interfejsu API Genie One należą do wywołującego użytkownika lub jednostki usługi. Pojawiają się także w historii czatu tego użytkownika w Genie One.

  • Lista rozmów: GET /api/2.0/genie/one/conversations zwraca rozmowy dzwoniącego z Genie One, ostatnio zaktualizowane jako pierwsze. Nie zawiera rozmów z Genie Agent. Użyj page_size (domyślnie 20, maksymalnie 100) i przekaż next_page_token jako page_token, aby uzyskać następną stronę.
  • Pobierz rozmowę: GET /api/2.0/genie/one/conversations/{conversation_id} zwraca tytuł rozmowy i znaczniki czasu, bez wiadomości.
  • Wypisz elementy rozmowy: GET /api/2.0/genie/one/conversations/{conversation_id}/items zwraca wiadomości użytkownika i asystenta w rozmowie. Użyj go do odbudowy historii czatów w aplikacji.
  • Usuń rozmowę: DELETE /api/2.0/genie/one/conversations/{conversation_id} usuwa rozmowę.

Na przykład, aby wymienić trzy najnowsze rozmowy:

curl "https://<workspace-url>/api/2.0/genie/one/conversations?page_size=3" \
  -H "Authorization: Bearer <access-token>"

Ograniczenia

  • Każde żądanie akceptuje jedno pytanie jako tekst, do 25 000 bajtów UTF-8. Obrazy, pliki i wiele wiadomości w jednym żądaniu nie są obsługiwane.
  • Rozmowa może mieć tylko jedną aktywną odpowiedź. Nowe pytanie w tej rozmowie zwraca HTTP 409 do czasu zakończenia aktywnej odpowiedzi.
  • Żądania są ograniczone w zależności od obszaru roboczego. Żądania powyżej limitu zwracają HTTP 429.

Najlepsze praktyki

  • Zapisz identyfikatory z response.created: Zapisz identyfikatory odpowiedzi i konwersacji zaraz po rozpoczęciu strumienia, aby móc odzyskać odpowiedź, jeśli połączenie się zerwie.
  • Ponawianie odrzuconych żądań z wykładniczym wydłużaniem odstępów: Gdy API zwraca odpowiedź błędu przed rozpoczęciem strumienia, taką jak 429, ponów próbę z rosnącym opóźnieniem między próbami. Po otrzymaniu response.created pobierz odpowiedź za pomocą GET zamiast ponownie wysyłać żądanie POST.
  • Nie próbuj ponownie na ślepo po przekroczeniu limitu czasu lub błędzie bramy: jeśli żądanie przekroczy limit czasu lub zwróci błąd bramy, taki jak 502 lub 504, zanim nadejdzie response.created, interfejs API mógł je zaakceptować. Ponowne wysłanie żądania POST może wtedy wywołać drugą odpowiedź.
  • Ponawiaj nieudane odpowiedzi tylko wtedy, gdy błąd nadaje się do ponowienia: Gdy odpowiedź się nie powiedzie, sprawdź response.error.retryable przed ponownym zadaniem pytania.
  • Rozpocznij nową rozmowę dla każdej sesji: Powtarzanie jednej rozmowy w niepowiązanych sesjach może obniżyć dokładność, ponieważ Genie One wykorzystuje wcześniejsze tury jako kontekst.
  • Rejestruj żądania i odpowiedzi: Rejestruj identyfikatory odpowiedzi, statusy i błędy, aby pomóc w debugowaniu i monitorowaniu użycia.

Rozwiązywanie problemów

Objaw Przyczyna i rozwiązanie
404 z komunikatem "Żądany zasób nie został znaleziony." Podgląd API Genie One jest wyłączony dla przestrzeni roboczej, identyfikator rozmowy lub odpowiedzi jest błędny, należy do innego użytkownika, albo magazyn nie jest dostępny dla dzwoniącego. Poproś administratora workspace, aby sprawdził stronę workspace Previews, a następnie sprawdź identyfikatory i uprawnienia wywołującego.
401 lub 403 Żądanie nie ma prawidłowego tokenu lub wywołujący nie może dodać odpowiedzi do rozmowy. Sprawdź swój token OAuth i jego genie zakres uprawnień. Zobacz Uwierzytelnij.
400 Z INVALID_PARAMETER_VALUE Ciało żądania zawiera nieznane pole lub nieobsługiwaną opcję, więcej niż jedną wiadomość lub pytanie dłuższe niż 25 000 bajtów. Wyślij tylko pola z referencji API.
409 Z ALREADY_EXISTS Inna odpowiedź jest aktywna w rozmowie. Poczekaj, aż się skończy, a potem spróbuj ponownie.
429 Z RESOURCE_EXHAUSTED Przestrzeń robocza przekroczyła limit liczby żądań. Ponów próbę z wycofywaniem wykładniczym. Zobacz Ograniczenia.
Strumień kończy się na response.failed Przetwarzanie odpowiedzi nie powiodło się po jej zaakceptowaniu. Czytaj response.error.message, i próbuj ponownie tylko wtedy, gdy response.error.retryable jest true.
Strumień rozłącza się przed zdarzeniem końcowym Pobierz odpowiedź z identyfikatorami z response.created. Zobacz Odzyskiwanie po utracie połączenia.

Pricing

API Genie One uruchamia Chat w Genie One, więc żądania są rozliczane tak samo jak w czacie Genie One. Zobacz Cennik usługi Genie.

Dodatkowe zasoby

  • Ostatnia aktualizacja o