Använd Genie One API:et

Important

Den här funktionen finns i Beta. En administratör för arbetsområdet måste slå på förhandsvisningen av Genie One API . Se kraven.

Genie One API låter din egen applikation, backend-tjänst eller agent ställa frågor på naturligt språk till Genie One om dina data via HTTP och strömma svaren tillbaka. Genie One arbetar med all data som användaren kan komma åt och grundar sina svar i Genie Ontology, så du behöver inte konfigurera en kuraterad agent först. Nya frågor körs med anroparens Unity Catalog-behörigheter, så svaren inkluderar endast data som anroparen kan komma åt. Att läsa ett sparat svar eller konversationshistorik returnerar det lagrade innehållet. Den kör inte om frågor/queries eller kontrollerar behörigheter på nytt på underliggande data.

Den här sidan förklarar hur man autentiserar, ställer frågor, strömmar svar och hanterar konversationer. För fullständiga förfrågnings- och svarsformat, se Genie One API-referensen.

Requirements

  • En administratör för arbetsytan måste slå på förhandsvisningen av Genie One API från arbetsytans sida för förhandsvisningar.
  • Uppringaren måste kunna använda Genie One. Consumer access-behörigheten eller någon högre arbetsytebehörighet räcker. Se Vad är konsumentåtkomst?.
  • Anroparen måste ha SELECT behörigheter på Unity-katalogens data som används av deras frågor.
  • För att köra frågor på ett specifikt SQL warehouse måste anroparen ha minst behörigheten CAN USE på det lagret. Om du inte specificerar ett lager väljer Genie One ett.

Authenticate

Genie One API accepterar OAuth-åtkomsttokens med omfånget genie.

  • För applikationer där en användare är närvarande, använd OAuth for users (OAuth U2M). Förfrågningar körs som den användaren, så svaren speglar användarens egna Unity Catalog-behörigheter.
  • För automatiserade arbetsbelastningar, använd en service principal med OAuth för service principals (OAuth M2M). Tjänstens huvudnamn måste ha tillgång till de data och SQL-lagerplatser som frågorna använder.

Du behöver också din workspace-URL. Exemplen på denna sida använder <workspace-url> för det. Se Skaffa identifierare för arbetsyteobjekt.

Ställ en fråga och streama svaret

Skicka en fråga till POST /api/2.0/genie/one/responses. slutpunkten returnerar ett text/event-stream svar som strömmar Genie Ones framsteg och slutliga svar som Server-Sent Events (SSE).

Starta en konversation

Utelämna conversation_id för att starta en ny konversation. Ställ in input för frågan:

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?"}'

Alternativet -N stänger av utbuffring så att curl skriver ut varje händelse när den anländer.

Python

Följande exempel använder Databricks SDK för Python enbart för att hantera din autentisering, så det fungerar med OAuth U2M, OAuth M2M eller en konfigurationsprofil. Den skickar förfrågan med biblioteket requests, lämnar över svaret och konversations-ID:n till en återanropsfunktion on_created så snart svaret accepteras, och återställer med en GET förfrågan om streamen avslutas i förtid. Sedan skrivs det slutgiltiga svaret ut.

Installera de paket som exemplet använder:

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"]))

Detta exempel väntar på terminalhändelsen. För att visa framsteg medan Genie One fungerar, hantera även utdataobjekthändelser, som beskrivs i Läs händelseströmmen.

Läs evenemangsströmmen

Varje händelse har ett SSE-namn event och en JSON-kropp data med en matchande type och en ökande sequence_number. En förkortad ström ser ut så här:

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]

Hantera evenemangen enligt följande:

  • response.created: Svaret är accepterat. Spara response.id och response.conversation_id. Du behöver att de ska ställa en följdfråga eller återhämta sig om strömmen kopplas bort.
  • response.output_item.added, response.output_item.updated, och response.output_item.done: Ett assistentmeddelande lades till, ändrades eller avslutades. Varje händelse bär hela meddelandet, så byt ut meddelandet vid output_index i stället för att lägga till text i det.
  • response.completed, response.failed, eller response.incomplete: Svaret nådde ett terminalt tillstånd. Arrayen response.output innehåller de slutliga assistentmeddelandena. Ström slutar sedan med data: [DONE].

Varje assistentmeddelande har ett phase. Meddelanden med taggen commentary beskriver Genie Ones framsteg medan den fungerar, och du kan visa dem som statusuppdateringar. Meddelandet med fasen final_answer är svaret. Svarstexten är Markdown och kan innehålla resultattabeller.

Om svaret misslyckas efter att det accepterats är HTTP-statusen fortfarande 200, och strömmen avslutas med en response.failed händelse. Objektet response.error beskriver misslyckandet. Se Felsökning.

Ställ en följdfråga

För att fortsätta en konversation, skicka vidare conversation_id från response.created. Genie One använder de tidigare frågorna och svaren som kontext.

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

Du kan också ställa in warehouse_id för att köra frågor på ett specifikt SQL Warehouse, och user_timezone till en IANA-tidszon, till exempel America/Los_Angeles, så att Genie One tolkar relativa datum i användarens tidszon.

Återanslut efter ett avbrott

Att koppla bort från dataströmmen avbryter inte responsen. Genie One fortsätter att arbeta, och du kan hämta resultatet med ID:n från response.created:

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

Begäran returnerar samma Response-objekt som terminalströmshändelsen. När status är in_progress, avsök endpointen med några sekunders intervall. Sluta när status är completed, failed, eller incomplete.

Skicka inte begäran om återställning igen POST Varje POST förfrågan startar ett nytt svar.

Läs källhänvisningar

Varje output_text del har en annotations array som listar källorna Genie One använde för den texten. Varje anteckning innehåller:

  • title: Källans visningsnamn.
  • asset_type: Typen av källa, såsom TABLE, NOTEBOOK, eller WEB.
  • identifier: Tillgångens identifierare, en volymsökväg eller en webbadress.
  • index: Det ettbaserade citeringsnumret som svarstexten hänvisar till.

Hantera konversationer

Samtal som du skapar med Genie One API tillhör den anropande användaren eller tjänstens huvudnamn. De dyker också upp i den användarens chatthistorik i Genie One.

  • Lista konversationer: GET /api/2.0/genie/one/conversations returnerar uppringarens Genie One-konversationer, senast uppdaterade först. Det inkluderar inte konversationer i Genie Agent. Använd page_size (standard 20, max 100) och skicka next_page_token som page_token för att få nästa sida.
  • Hämta en konversation: GET /api/2.0/genie/one/conversations/{conversation_id} returnerar konversationens titel och tidsstämplar, utan dess meddelanden.
  • Lista konversationspunkter: GET /api/2.0/genie/one/conversations/{conversation_id}/items returnerar användar- och assistentmeddelanden i konversationen. Använd den för att bygga om en chatthistorik i din applikation.
  • Radera en konversation: DELETE /api/2.0/genie/one/conversations/{conversation_id} raderar konversationen.

Till exempel, för att lista dina tre senaste konversationer:

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

Begränsningar

  • Varje förfrågan accepterar en fråga som text, upp till 25 000 UTF-8 byte. Bilder, filer och flera meddelanden i en och samma förfrågan stöds inte.
  • En konversation kan bara ha ett aktivt svar. En ny fråga i den konversationen returnerar HTTP 409 tills det aktiva svaret är klart.
  • Förfrågningar är hastighetsbegränsade per arbetsyta. Förfrågningar över gränsen returnerar HTTP 429.

Regelverk

  • Spara ID:n från response.created: Spara svars- och konversations-ID:n så snart strömmen startar, så att du kan återställa svaret om anslutningen bryts.
  • Försök igen med avvisade förfrågningar med exponentiell backoff: När API:et returnerar ett felsvar innan strömmen startar, såsom 429, försök igen med ökande fördröjning mellan försöken. Efter att du mottagit response.created, hämta svaret med GET istället för att skicka POST-begäran igen.
  • Försök inte blint igen efter en timeout eller gateway-fel: Om en begäran går ut på tiden eller returnerar ett gateway-fel som 502 eller 504 innan response.created kommer, kan API:et ändå ha accepterat det. Att skicka begäran POST igen kan då skapa ett andra svar.
  • Försök igen för misslyckade svar endast när felet kan försökas igen: När ett svar misslyckas, kontrollera response.error.retryable innan du ställer frågan igen.
  • Starta en ny konversation för varje session: Att återanvända en konversation över orelaterade sessioner kan minska noggrannheten eftersom Genie One använder tidigare meddelanden som kontext.
  • Logga förfrågningar och svar: Logga svars-ID:n, statusar och fel för att hjälpa till med felsökning och övervakning av användning.

Felsökning

Symtom Orsak och åtgärd
404 med meddelandet "Den begärda resursen hittades inte." Genie One API-förhandsvisningen är avstängd för arbetsområdet, ett konversations- eller svars-ID är fel eller tillhör en annan användare, eller datalagret är inte tillgängligt för den som ringer. Be en administratör för arbetsområdet att kontrollera arbetsområdets Förhandsvisningar-sida och kontrollera sedan ID:n och anroparens behörigheter.
401 eller 403 Förfrågan har ingen giltig token, eller så kan anroparen inte lägga till något svar i konversationen. Kontrollera din OAuth-token och dess genie scope. Se Autentisera.
400 med INVALID_PARAMETER_VALUE Begäranarkroppen har ett okänt fält eller ett alternativ som inte stöds, mer än ett meddelande eller en fråga längre än 25 000 byte. Skicka endast fälten i API-referensen.
409 med ALREADY_EXISTS Ett annat svar är aktivt i samtalet. Vänta tills det är klart, försök sedan igen.
429 med RESOURCE_EXHAUSTED Arbetsutrymmet överskred gränsen för antal förfrågningar. Försök igen med exponentiell backoff. Se Begränsningar.
Strömmen slutar med response.failed Svaret misslyckades efter att det accepterats. Läs response.error.message, och försök igen endast om response.error.retryable är true.
Strömmen kopplas bort innan en avslutande händelse Hämta svaret med ID:n från response.created. Se Återanslut efter en avbruten anslutning.

Pricing

Genie One API kör Chat i Genie One, så förfrågningar faktureras på samma sätt som Genie One-chatten. Se Genie-priser.

Ytterligare resurser

  • Uppdaterades senast