Utiliser l’API Genie One

info

Bêta

Cette fonctionnalité est en Beta. Un administrateur de workspace doit activer la préversion de l' API Genie One . Voir Prérequis.

L’API Genie One permet à votre propre application, service backend ou agent de poser à Genie One des questions en langage naturel sur vos données via HTTP et de recevoir les réponses en Stream. Genie One fonctionne sur toutes les données auxquelles l’appelant peut accéder et fonde ses réponses sur Genie Ontology, vous n’avez donc pas besoin de configurer un agent dédié au préalable. Les nouvelles questions s’exécutent avec les permissions Unity Catalog de l’appelant. Les réponses ne contiennent donc que les données auxquelles l’appelant peut accéder. La lecture d’une réponse enregistrée ou de l’historique de la conversation renvoie le contenu stocké. Il ne réexécute pas les requêtes et ne revérifie pas les permissions sur les données sous-jacentes.

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

Prérequis

Un administrateur de workspace doit activer la fonctionnalité en préversion Genie One API depuis la page des préversions du workspace.
L’appelant doit être en mesure d’utiliser Genie One. Le droit d' accès consommateur ou tout droit d'accès supérieur au workspace est suffisant. Voir Qu’est-ce que l’accès consommateur ?.
L’appelant doit disposer des privilèges SELECT sur les données Unity Catalog utilisées par ses questions.
Pour exécuter des queries sur un SQL warehouse spécifique, l’appelant doit disposer d’au moins l’autorisation CAN USE sur ce warehouse. Si vous ne spécifiez pas de warehouse, Genie One en choisit un.

Authentifier

L'API Genie One accepte les jetons d'accès OAuth avec l'étendue 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, de sorte que les réponses reflètent les propres autorisations Unity Catalog de l'utilisateur.
Pour les workloads automatisés, utilisez un service principal avec OAuth pour les services principaux (OAuth M2M). Le Service Principal doit avoir accès aux données et aux SQL Warehouse que ses questions utilisent.

Vous avez également besoin de l'URL de votre workspace. Les exemples de cette page utilisent <workspace-url> pour cela. Consultez Obtenir des identifiants pour des objets de workspace.

Posez une question et obtenez la réponse Stream

Envoyer une question à POST /api/2.0/genie/one/responses. L’endpoint renvoie une réponse text/event-stream qui diffuse la progression et la réponse finale de Genie One sous forme d’événements envoyés par le serveur (SSE).

start une conversation

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

curl
Python

Bash
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 la mise en mémoire tampon de la sortie pour que curl imprime chaque événement à son arrivée.

L’exemple suivant utilise uniquement le SDK Databricks pour Python pour résoudre votre authentification ; il fonctionne donc avec OAuth U2M, OAuth M2M ou un profil de configuration. Il envoie la requête avec la bibliothèque requests, transmet les ID de réponse et de conversation à un callback on_created dès que la réponse est acceptée et récupère avec une requête GET si le stream se termine prématurément. Il imprime ensuite la réponse finale.

Installez les packages utilisés par l'exemple :

Bash
pip install databricks-sdk requests

Python
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 afficher la progression pendant le travail de Genie One, gérez également les événements de l'élément de sortie, comme décrit dans Lire le Stream d'événements.

Lire le flux d’événements Stream

Chaque événement possède un nom de SSE event et un corps JSON data avec une correspondance type et une augmentation de sequence_number. Un stream raccourci se présente comme suit :

Text
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]

Traitez les événements comme suit :

response.created : La réponse est acceptée. Enregistrez response.id et response.conversation_id. Vous en avez besoin pour poser une question de suivi ou pour récupérer si le Stream est déconnecté.
response.output_item.added , response.output_item.updated et response.output_item.done : un message de l'assistant a été ajouté, modifié ou terminé. Chaque événement contient le message complet. Remplacez le message au niveau de output_index plutôt que d'y ajouter du texte.
response.completed , response.failed ou response.incomplete : la réponse a atteint un état terminal. Le tableau response.output contient les messages finaux de l’assistant. Le Stream se termine ensuite avec data: [DONE].

Chaque message de l’assistant possède un phase. Les messages avec la phase commentary décrivent la progression de Genie One pendant son travail, et vous pouvez les afficher comme mises à jour d'état. Le message avec la phase final_answer est la réponse. Le texte de réponse est au format Markdown et peut inclure des tables de résultats.

Si la réponse échoue après avoir été acceptée, le statut HTTP est toujours 200 et le stream se termine par un événement response.failed. L’objet response.error décrit l’échec. Voir Dépannage.

Poser une question de suivi

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

Bash
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 également définir warehouse_id pour exécuter des queries sur un SQL warehouse spécifique, et user_timezone sur un fuseau horaire IANA tel que America/Los_Angeles afin que Genie One interprète les dates relatives dans le fuseau horaire de l’utilisateur.

Récupération après une connexion interrompue

La déconnexion du Stream n'annule pas la réponse. Genie One continue de travailler, et vous pouvez récupérer le résultat avec les IDs à partir de response.created:

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

La requête retourne le même objet Response que l’événement de stream terminal. Pendant que status est in_progress, interrogez l’endpoint toutes les quelques secondes. Arrêtez lorsque status est completed, failed ou incomplete.

Ne renvoyez pas la requête POST pour la récupération. Chaque requête POST start une nouvelle réponse.

Lire les citations

Chaque partie output_text possède un tableau annotations qui répertorie 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’asset, le chemin de volume ou une URL web.
index: le numéro de citation basé sur un, auquel le texte de la 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 Service Principal. Elles apparaissent également dans l’historique de chat de cet utilisateur dans Genie One.

Lister les conversations : GET /api/2.0/genie/one/conversations renvoie les conversations Genie One de l’appelant, de la plus récemment mise à jour à la plus ancienne. Il n’inclut pas les conversations Genie Agent. Utilisez page_size (20 par default, 100 maximum) et transmettez next_page_token comme page_token pour obtenir la page suivante.
Obtenir une conversation : GET /api/2.0/genie/one/conversations/{conversation_id} retourne le titre et les Timestamp de la conversation, sans ses messages.
Lister les éléments de 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 chat dans votre application.
Supprimer une conversation : DELETE /api/2.0/genie/one/conversations/{conversation_id} supprime la conversation.

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

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

Limitations

Chaque requête accepte une question sous forme de texte, jusqu’à 25 000 octets UTF-8. Les images, les fichiers et plusieurs messages dans une seule 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 retourne HTTP 409 jusqu’à la fin de la réponse active.
Les requêtes sont limitées par workspace. Les requêtes dépassant la limite renvoient HTTP 429.

Bonnes pratiques

Enregistrez les ID de response.created : stockez la réponse et les ID de conversation dès que le Stream start afin de pouvoir récupérer la réponse en cas de coupure de la connexion.
Réessayer les demandes rejetées avec un backoff exponentiel : lorsque l'API renvoie une réponse d'erreur avant le start du Stream, telle que 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 timeout ou une erreur de passerelle : si une requête expire ou renvoie une erreur de passerelle telle que 502 ou 504 avant l’arrivée de response.created, l’API pourrait l’avoir acceptée. Renvoyer la requête POST peut alors créer une seconde réponse.
Réessayer les réponses échouées uniquement lorsque l’erreur peut être relancée : lorsqu’une réponse échoue, vérifiez response.error.retryable avant de poser à nouveau la question.
start une nouvelle conversation pour chaque session : réutiliser une conversation pour des sessions sans rapport peut réduire la précision car Genie One utilise les échanges précédents comme contexte.
Enregistrer les requêtes et les réponses : enregistrez les ID de réponse, les statuts et les erreurs pour vous aider à debugging et à surveiller l'utilisation monitoring.

Dépannage

Symptôme	Cause et résolution
`404` avec le message "La ressource demandée est introuvable."	La préversion de l' API Genie One est désactivée pour le workspace, un identifiant de conversation ou de réponse est incorrect ou appartient à un autre utilisateur, ou le warehouse n'est pas disponible pour l'appelant. Demandez à un administrateur de workspace de vérifier la page des préversions du workspace, puis vérifiez les identifiants et les autorisations de l'appelant.
`401` OU `403`	La requête ne contient aucun jeton valide, ou l'appelant ne peut pas ajouter de réponse à la conversation. Vérifiez votre jeton OAuth et sa portée `genie`. Consultez Authentification.
`400` avec `INVALID_PARAMETER_VALUE`	Le corps de la requête possède un champ inconnu ou une option non prise en charge, plusieurs messages ou une question supérieure à 25 000 octets. Envoyez uniquement les champs de la référence de l’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`	Le workspace a dépassé la limite de vitesse. Réessayez avec un intervalle exponentiel. Voir Limitations.
Le Stream se termine par `response.failed`	La réponse a échoué après avoir été acceptée. Lisez `response.error.message` et réessayez uniquement si `response.error.retryable` est `true`.
Le Stream se déconnecte avant un événement terminal	Récupérez la réponse avec les ID de `response.created`. Voir Récupérer suite à une connexion interrompue.

Symptôme	Cause et résolution
`404` avec le message "La ressource demandée est introuvable."	La préversion de l' API Genie One est désactivée pour le workspace, un identifiant de conversation ou de réponse est incorrect ou appartient à un autre utilisateur, ou le warehouse n'est pas disponible pour l'appelant. Demandez à un administrateur de workspace de vérifier la page des préversions du workspace, puis vérifiez les identifiants et les autorisations de l'appelant.
`401` OU `403`	La requête ne contient aucun jeton valide, ou l'appelant ne peut pas ajouter de réponse à la conversation. Vérifiez votre jeton OAuth et sa portée `genie`. Consultez Authentification.
`400` avec `INVALID_PARAMETER_VALUE`	Le corps de la requête possède un champ inconnu ou une option non prise en charge, plusieurs messages ou une question supérieure à 25 000 octets. Envoyez uniquement les champs de la référence de l’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`	Le workspace a dépassé la limite de vitesse. Réessayez avec un intervalle exponentiel. Voir Limitations.
Le Stream se termine par `response.failed`	La réponse a échoué après avoir été acceptée. Lisez `response.error.message` et réessayez uniquement si `response.error.retryable` est `true`.
Le Stream se déconnecte avant un événement terminal	Récupérez la réponse avec les ID de `response.created`. Voir Récupérer suite à une connexion interrompue.

Tarifs

L’API Genie One exécute Chat in Genie One, de sorte que les requêtes sont facturées de la même manière que le chat Genie One. Voir les Tarifs de Genie.

Ressources supplémentaires

Référence de l’API Genie One : réponse pour les Endpoint de création et d’obtention de réponse et le Stream d’événements.
Référence de l'API Genie One : Conversation pour les Endpoint de conversation.
Chattez dans Genie One pour apprendre comment Genie One répond aux questions.
Utilisez l’API Genie Agents pour query un agent Genie Agent sélectionné.
Serveur Genie One MCP pour connecter un client ou un agent MCP à Genie One.

Prérequis​

Authentifier​

Posez une question et obtenez la réponse Stream​

start une conversation​

Lire le flux d’événements Stream​

Poser une question de suivi​

Récupération après une connexion interrompue​

Lire les citations​

Gérer les conversations​

Limitations​

Bonnes pratiques​

Dépannage​

Tarifs​

Ressources supplémentaires​