Utilisez l’API Genie One

Important

Cette fonctionnalité est en version bêta. Un administrateur d’espace de travail doit activer l’aperçu de Genie One API. Consultez Spécifications.

L’API Genie One permet à votre propre application, service backend ou agent de poser des questions en langage naturel sur vos données via HTTP et de remettre les réponses en streaming. Genie One fonctionne sur l’ensemble des données auxquelles l’appelant peut accéder et fonde ses réponses sur Genie Ontology, donc vous n’avez pas besoin de configurer d’abord un agent préconfiguré. Les nouvelles questions s’exécutent avec les permissions du catalogue Unity de l’appelant, de sorte que les réponses ne contiennent que les données accessibles par l’appelant. La lecture d’une réponse sauvegardée ou d’un historique de conversation renvoie le contenu stocké. Il ne relance pas les requêtes ni ne revérifie les permissions sur les données sous-jacentes.

Cette page explique comment s’authentifier, poser des questions, diffuser les réponses et gérer les conversations. Pour les formats complets de requête et de réponse, voir la référence API Genie One.

Requirements

  • Un administrateur d’espace de travail doit activer l’aperçu Genie One API depuis la page Préversions de l’espace de travail.
  • L’appelant doit pouvoir utiliser Genie One. Le droit d’accès client ou tout droit d’espace de travail supérieur suffit. Voir Qu’est-ce que l’accès au consommateur ?.
  • L’appelant doit avoir les privilèges SELECT sur les données du catalogue Unity utilisées par ses questions.
  • Pour lancer des requêtes sur un entrepôt SQL spécifique, l’appelant doit avoir au moins l’autorisation CAN USE sur cet entrepôt. Si vous ne précisez pas d’entrepôt, Genie One en choisit un.

Authenticate

L’API Genie One accepte les jetons d’accès OAuth avec la portée genie.

  • Pour les applications où un utilisateur est présent, utilisez OAuth pour les utilisateurs (OAuth U2M). Les requêtes s’exécutent en tant que cet utilisateur, donc les réponses reflètent les permissions du catalogue Unity de l’utilisateur.
  • Pour les charges de travail automatisées, utilisez un principal du service avec OAuth pour les principaux du service (OAuth M2M). Le principal de service doit avoir accès aux entrepôts de données et SQL que ses questions utilisent.

Vous avez aussi besoin de l’URL de votre espace de travail. Les exemples sur cette page utilisent <workspace-url> pour cela. Consultez Obtenir des identificateurs pour les objets d’espace de travail.

Posez une question et recevez la réponse en continu

Envoyez une question à POST /api/2.0/genie/one/responses. Le point de terminaison renvoie une text/event-stream réponse qui diffuse la progression et la réponse finale de Genie One sous forme d’événements Server-Sent (SSE).

Engage une conversation

Omettez conversation_id pour commencer une nouvelle conversation. Définissez input sur la question :

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

L’option -N désactive le tampon de sortie afin que le curl imprime chaque événement au fur et à mesure qu’il arrive.

Python

L’exemple suivant utilise le SDK Databricks pour Python uniquement pour gérer votre authentification, donc il fonctionne avec OAuth U2M, OAuth M2M ou un profil de configuration. Il envoie la requête à la requests bibliothèque, remet les identifiants de réponse et de conversation à un on_created callback dès que la réponse est acceptée, et reprend avec une GET requête si le flux se termine plus tôt. Il affiche ensuite la réponse finale.

Installez les paquets utilisés dans l’exemple :

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

Cet exemple attend l’événement terminal. Pour montrer la progression pendant que Genie One fonctionne, gérez également les événements d’élément de sortie, comme décrit dans Lire le flux d’événements.

Lisez le flux d’événements

Chaque événement a un nom SSE event et un corps JSON data avec un identifiant correspondant type et un identifiant croissant sequence_number. Un flux raccourci ressemble à ceci :

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]

Gérez les événements comme suit :

  • response.created: La réponse est acceptée. Enregistrer response.id et response.conversation_id. Vous avez besoin qu’ils posent une question de suivi ou de reprendre si le flux est interrompu.
  • response.output_item.added, response.output_item.updated, et response.output_item.done: Un message d’assistant a été ajouté, modifié ou terminé. Chaque événement porte le message complet, donc remplacez le message à l’emplacement output_index au lieu d’y ajouter du texte.
  • response.completed, response.failed, ou response.incomplete: La réponse atteignit un état terminal. Le response.output tableau contient les messages d’assistant finaux. Le flux se termine alors par data: [DONE].

Chaque message d’assistant contient un phase. Les messages marqués par la phase commentary décrivent les progrès de Genie One pendant qu’il fonctionne, et vous pouvez les afficher comme des mises à jour de statut. Le message comportant final_answer est la réponse. Le texte de la réponse est Markdown et peut inclure des tableaux de résultats.

Si la réponse échoue après avoir été acceptée, le statut HTTP reste 200, et le flux se termine par l’événement response.failed. L’objet response.error décrit la défaillance. Consultez la rubrique Résolution des problèmes.

Posez une question de suivi

Pour poursuivre une conversation, passez le conversation_id depuis response.created. Genie One utilise les questions et réponses précédentes comme contexte.

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

Vous pouvez aussi configurer warehouse_id pour exécuter des requêtes sur un entrepôt SQL spécifique, et user_timezone sur un fuseau horaire IANA spécifique tel que America/Los_Angeles afin que Genie One interprète les dates relatives dans le fuseau horaire de l’utilisateur.

Récupérer après une coupure de connexion

Se déconnecter du stream n’annule pas la réponse. Genie One continue de fonctionner, et vous pouvez récupérer le résultat avec les identifiants depuis response.created:

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

La requête renvoie le même objet Response que l’événement du flux terminal. Tant que status est in_progress, interroge le point de terminaison toutes les quelques secondes. Arrêter lorsque status est completed, failed, ou incomplete.

Ne renvoyez pas la demande de récupération POST. Chaque POST demande déclenche une nouvelle réponse.

Lire les citations

Chaque output_text partie possède un annotations tableau listant les sources utilisées par Genie One pour ce texte. Chaque annotation inclut :

  • title: Le nom d’affichage de la source.
  • asset_type: Le type de source, tel que TABLE, NOTEBOOK, ou WEB.
  • identifier: L’identifiant de l’actif, un chemin de volume ou une URL web.
  • index : Le numéro de citation commençant à 1 auquel le texte de réponse fait référence.

Gérer les conversations

Les conversations que vous créez avec l’API Genie One appartiennent à l’utilisateur appelant ou au principal du service. Ils apparaissent également dans l’historique de discussion de cet utilisateur dans Genie One.

  • Liste des conversations : GET /api/2.0/genie/one/conversations renvoie les conversations Genie One de l’appelant, mises à jour les plus récentes en premier. Il n’inclut pas les conversations avec Genie Agent. Utilisez page_size (par défaut 20, maximum 100) et passez next_page_token comme page_token pour obtenir la page suivante.
  • Récupérer une conversation : GET /api/2.0/genie/one/conversations/{conversation_id} renvoie le titre et les horodatages de la conversation, sans ses messages.
  • Listez les éléments de la conversation : GET /api/2.0/genie/one/conversations/{conversation_id}/items renvoie les messages de l’utilisateur et de l’assistant dans la conversation. Utilisez-le pour reconstruire un historique de discussion dans votre application.
  • Supprimer une conversation : DELETE /api/2.0/genie/one/conversations/{conversation_id} supprime la conversation.

Par exemple, pour énumérer vos trois conversations les plus récentes :

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

Limites

  • Chaque demande accepte une question en texte, jusqu’à 25 000 octets UTF-8. Les images, fichiers et messages multiples dans une même requête ne sont pas pris en charge.
  • Une conversation ne peut avoir qu’une seule réponse active. Une nouvelle question dans cette conversation renvoie HTTP 409 jusqu’à ce que la réponse active soit terminée.
  • Les requêtes font l’objet d’une limitation de débit par espace de travail. Les requêtes au-dessus de la limite retournent HTTP 429.

Bonnes pratiques

  • Enregistrez les identifiants depuis response.created : Stockez les identifiants de réponse et de conversation dès que le flux commence, afin de pouvoir récupérer la réponse si la connexion est interrompue.
  • Réessayez les requêtes rejetées avec un backoff exponentiel : Lorsque l’API renvoie une réponse d’erreur avant le début du flux, comme 429, réessayez avec un délai croissant entre les tentatives. Après avoir reçu response.created, récupérez la réponse avec GET au lieu de renvoyer la requête POST.
  • Ne réessayez pas aveuglément après un délai d’attente ou une erreur de passerelle : si une requête expire ou renvoie une erreur de passerelle comme 502 ou 504 avant que response.created n’arrive, l’API pourrait quand même l’avoir acceptée. Renvoyer la requête POST peut alors créer une seconde réponse.
  • Réessayez les réponses ayant échoué uniquement lorsque l’erreur peut faire l’objet d’une nouvelle tentative : lorsqu’une réponse échoue, vérifiez response.error.retryable avant de reposer la question.
  • Commencez une nouvelle conversation pour chaque session : Réutiliser une conversation à travers des sessions sans lien peut réduire la précision car Genie One utilise les tours précédents comme contexte.
  • Journaliser les requêtes et les réponses : identifiez les identifiants, statuts et erreurs des réponses, pour aider au débogage et à la surveillance de leur utilisation.

Résolution des problèmes

Symptôme Cause et correction
404 avec le message « La ressource demandée n’a pas été trouvée. » L’aperçu de l’API Genie One est désactivé pour l’espace de travail, un identifiant de conversation ou de réponse est incorrect ou appartient à un autre utilisateur, ou l’entrepôt n’est pas disponible pour l’appelant. Demandez à un administrateur de l’espace de travail de vérifier la page Aperçus de l’espace de travail, puis vérifiez les identifiants et les autorisations de l’appelant.
401 ou 403 La requête n’a pas de jeton valide, ou l’appelant ne peut pas ajouter de réponse à la conversation. Vérifie ton token OAuth et sa genie portée. Voir Authentification.
400 avec INVALID_PARAMETER_VALUE Le corps de la requête comporte un champ inconnu ou une option non prise en charge, plus d’un message, ou une question de plus de 25 000 octets. N’envoyez que les champs figurant dans la référence API.
409 avec ALREADY_EXISTS Une autre réponse est active dans la conversation. Attendez qu’il se termine, puis réessayez.
429 avec RESOURCE_EXHAUSTED L’espace de travail dépassait la limite de débit. Réessayez avec un retrait exponentiel. Consultez Limitations.
Le flux se termine par response.failed La réponse a échoué après avoir été acceptée. Lisez response.error.message, et ne réessayez que si response.error.retryable est true.
Le flux se déconnecte avant un événement terminal Récupérez la réponse avec les identifiants depuis response.created. Voir Récupérer après une perte de connexion.

Pricing

L’API Genie One fait tourner le chat dans Genie One, donc les requêtes sont facturées de la même manière que le chat Genie One. Consultez la tarification de Genie.

Ressources supplémentaires

  • Dernière mise à jour :