Présentation de l’article : AI Chat v2 conserve le mode d’appel simple de l’interface de conversation originale, tout en ajoutant les entrées multimodales, les flux d’événements structurés, l’appel automatique d’outils, la suspension et la reprise, l’exécution asynchrone et la gestion des conversations. Cet article part d’une migration ne nécessitant presque aucune réécriture de code, et explique clairement comment ces changements influencent le développement réel de produits.

De nombreuses interfaces de chat sont très faciles à utiliser pendant la phase de démonstration : on transmet une question, on attend que le modèle retourne un texte, puis on affiche ce texte sur la page.

Lorsque le produit continue d’évoluer, il ne s’agit plus simplement de « poser une question, obtenir une réponse ». Les utilisateurs téléversent des PDF et des captures d’écran, le modèle doit rechercher sur le Web, lire des fichiers, voire appeler des outils GitHub, Notion et autres déjà autorisés. Une tâche peut durer plusieurs tours, et s’interrompre en cours de route pour demander des précisions faute d’informations. À ce stade, si l’interface ne retourne toujours qu’une chaîne de texte qui s’allonge continuellement, le frontend a du mal à savoir ce que fait le modèle, et le backend a également du mal à déterminer si la tâche est réellement terminée.

C’est précisément ce problème que résout l’API Ace Data Cloud AI Chat v2. Elle ne renverse pas le mode de conversation d’origine, mais, tout en restant compatible avec les appels simples, elle décompose une réponse en événements que les programmes peuvent reconnaître et traiter : le corps du texte reste le corps du texte, les appels d’outils restent les appels d’outils, et les citations, fichiers, erreurs et états finaux ont chacun un emplacement clair.

Ace Data Cloud AI Chat v2 : entrées multimodales, outils Agent et flux d’événements structurés

Illustration : AI Chat v2 ne compresse plus l’ensemble de la tâche en un seul texte, mais préserve la structure des événements d’entrée, d’outils et de sortie.

La migration peut commencer par la modification d’une seule adresse

Si le projet utilise actuellement l’ancienne version de /aichat/conversations, il n’est pas nécessaire de réécrire d’abord la structure des messages, ni de créer d’emblée une interface Agent. V2 continue d’accepter les champs originaux tels que model, question, stateful, id, references et preset. La migration minimale consiste uniquement à remplacer l’adresse de requête par :

https://api.acedata.cloud/aichat2/conversations

Une requête très basique reste courte :

curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer YOUR_API_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
    "model": "YOUR_SUPPORTED_MODEL",
    "question": "请概括这份需求里最重要的三个问题。",
    "stateful": true
  }'

En mode JSON standard, l’interface retourne toujours un résultat familier :

{
  "answer": "...",
  "id": "conversation-uuid"
}

Enregistrez l’id retourné et incluez le même id dans la requête suivante pour pouvoir poursuivre la conversation. stateful vaut true par défaut et permet de contrôler si le contexte d’une conversation enregistrée doit être chargé et poursuivi.

Cette étape convient très bien aux projets réels : vérifiez d’abord que l’authentification, le modèle, la latence et les fonctionnalités métier existantes fonctionnent correctement, puis intégrez progressivement les nouvelles capacités. La migration n’a pas besoin d’être liée à la refonte de l’interface lors d’une même mise en production.

Lorsque les fichiers et les images entrent dans la conversation, l’ordre devient aussi une information

L’ancien question convient au texte pur. Pour des tâches telles que « lire d’abord le rapport, puis le comparer à la capture d’écran, et enfin tirer une conclusion », une simple liste de pièces jointes n’est plus assez précise. V2 ajoute un tableau message structuré, permettant d’insérer dans l’ordre du texte, des images et des fichiers :

{
  "model": "YOUR_SUPPORTED_MODEL",
  "stateful": true,
  "message": [
    {
      "type": "text",
      "text": "阅读报告,并把其中的趋势与后面的仪表盘截图进行对照。"
    },
    {
      "type": "file_url",
      "file_url": {"url": "https://example.com/report.pdf"}
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://example.com/dashboard.png"}
    }
  ]
}

Les blocs de contenu disponibles incluent text, image_url et file_url. L’important n’est pas seulement de « prendre en charge les pièces jointes », mais aussi que les relations entre les contenus ne soient pas perdues lors de la transmission. Le client peut indiquer clairement au modèle : quelle partie correspond aux instructions de la tâche, quel document constitue le matériau source, et ce qui doit ensuite être comparé.

Afin de permettre une migration fluide des anciens clients, V2 reconnaît toujours references. Les URL dont l’extension correspond à une image seront traitées comme des images, et les autres URL seront traitées comme des fichiers. S’il s’agit seulement de mettre à niveau l’interface, vous pouvez temporairement conserver l’ancienne écriture ; si l’ordre des entrées influence la compréhension, il est recommandé d’utiliser message.

La réponse en streaming ne se limite plus à « être en train d’écrire »

Les sorties en streaming traditionnelles ne contiennent généralement que des incréments de texte. Lorsque le modèle commence à effectuer des recherches, à lire des fichiers ou à appeler des outils externes, la page semble bloquée, les utilisateurs ne savent pas si la tâche continue, et les développeurs ne disposent pas d’un état clair.

AI Chat v2 propose trois modes de réponse via l’en-tête de requête accept :

Cas d’utilisation accept Mode de retour
Requête serveur simple application/json Retourne {answer, id} une fois terminé
Node, Python, CLI ou Worker application/x-ndjson Un événement JSON par ligne
Frontend Web text/event-stream Flux d’événements SSE

Dans les modes NDJSON et SSE, le retour ne contient pas seulement des tokens, mais un ensemble d’événements typés. text_delta est utilisé pour les incréments du corps du texte, tool_use indique que le modèle s’apprête à appeler un outil, tool_result retourne le résultat de l’outil, citation fournit les sources citées, card et artifact transportent des cartes ou des livrables pouvant être affichés séparément, error indique l’échec du tour en cours, et done fournit l’utilisation et la raison de fin.

Le client Python ci-dessous assemble le corps du texte tout en conservant les états clés :

import json
import os
import requests

url = "https://api.acedata.cloud/aichat2/conversations"
headers = {
    "accept": "application/x-ndjson",
    "authorization": f"Bearer {os.environ['ACEDATA_API_TOKEN']}",
    "content-type": "application/json",
}
payload = {
    "model": os.environ["ACEDATA_CHAT_MODEL"],
    "question": "检索资料,给出带来源的简要结论。",
    "stateful": True,
}

with requests.post(url, json=payload, headers=headers,
                   stream=True, timeout=120) as response:
    response.raise_for_status()
    answer = []
    for raw_line in response.iter_lines():
        if not raw_line:
            continue
        event = json.loads(raw_line)
        event_type = event.get("type")
        if event_type == "text_delta":
            answer.append(event.get("content", ""))
        elif event_type == "tool_use":
            print("开始调用:", event.get("tool_name"))
        elif event_type == "tool_result":
            print("工具是否失败:", event.get("is_error"))
        elif event_type == "error":
            raise RuntimeError(event.get("message", "未知错误"))
        elif event_type == "done":
            print("用量:", event.get("usage"))
            print("终止原因:", event.get("terminal_reason"))

print("".join(answer))

Si le produit ne s'intéresse qu'au texte final, il suffit de concaténer tous les text_delta.content ; si vous souhaitez créer une interface Agent observable, vous pouvez afficher séparément les appels d'outils, les citations, les artefacts et les états. Les deux besoins utilisent la même interface, sans devoir maintenir deux protocoles pour le « chat simple » et les « tâches complexes ».

Les appels d'outils sont disponibles par défaut, mais le produit doit toujours définir clairement les limites

V2 permet au modèle d'appeler, selon les besoins de la tâche, des capacités intégrées telles que la recherche Web, l'extraction de pages et la lecture de fichiers ; après que l'utilisateur a connecté et autorisé les services correspondants, il peut également utiliser des outils MCP pour traiter des données externes telles que GitHub et Notion.

Le flux fait apparaître séparément tool_use et tool_result, qui sont appariés via tool_id. Le frontend peut ainsi afficher la progression réelle, et le backend peut également enregistrer la durée et le point d'échec de chaque outil.

Le fait que les outils puissent être appelés automatiquement ne signifie pas que le périmètre d'exécution doit être ouvert sans limites. max_turns sert à contraindre le nombre d'itérations Agent dans une requête ; la plage indiquée par la documentation est de 1 à 500 ; lorsqu'il est défini sur 1, ce tour n'effectue qu'un seul appel au modèle et ne poursuit pas avec des appels d'outils. En environnement de production, il convient de le définir activement selon la complexité de la tâche, le temps de réponse et le budget de coûts, plutôt que de dépendre durablement d'une limite par défaut élevée.

Pour les Webhooks, les CI/CD ou les tâches de surveillance, V2 prend en charge async: true : les tâches peuvent être exécutées en arrière-plan, et les résultats peuvent être obtenus par requête ou via callback_url. Mais les actions impliquant l'envoi, la publication ou l'écriture nécessitent une préautorisation explicite via allowed_skills, allowed_mcp_servers ou unattended_policy.

La connexion résout la question de « pouvoir accéder ou non », tandis que la politique d'autorisation résout celle de « pouvoir ou non agir à la place de l'utilisateur cette fois-ci ». Ces deux choses ne doivent pas être confondues.

Lorsqu'un Agent manque d'informations, il ne doit pas prétendre que la tâche est déjà terminée

Les tâches complexes se bloquent souvent sur des questions précises : sur quel canal publier, quel format adopter, s'il faut écraser des fichiers existants. V2 fournit à cet effet l'événement ask_user_question. Après l'apparition de l'événement, la conversation entre dans un état d'attente de saisie utilisateur.

Le client enregistre l'id de la conversation actuelle et le tool_id correspondant, affiche la question et recueille la réponse, puis, avec le même id de conversation, renvoie la réponse via tool_results, et la tâche peut reprendre à partir du point de pause. Ce mécanisme convient également à la création d'étapes d'approbation. Plutôt que de laisser le modèle deviner lui-même lorsque les informations sont insuffisantes, il vaut mieux rendre les choix manquants à l'utilisateur.

La conversation elle-même peut également être gérée

V2 ajoute un CRUD léger de conversations dans le même point de terminaison, en distinguant retrieve, retrieve_batch, update et delete via action.

retrieve_batch renvoie des résumés sans inclure les messages complets, ce qui convient à une barre latérale de conversations ; lorsque l'utilisateur ouvre réellement une conversation, appelez ensuite retrieve pour lire le contenu. Pour les longues conversations, la consolidation du contexte côté serveur ne remplacera pas les messages bruts enregistrés par des résumés. Lorsqu'il faut continuer à modifier un article, vérifier des chiffres ou préparer une publication, il faut toujours lire le texte original, et non utiliser le résumé à la place du contenu.

Avant la mise en ligne, ne vérifiez pas seulement « si du texte est renvoyé »

Après l'intégration d'une interface Agent, recevoir une partie du texte ne signifie pas que ce tour est terminé de manière fiable ; la fin du flux ne représente pas nécessairement non plus le succès de la tâche. Le client doit traiter error et enregistrer usage et terminal_reason après avoir reçu done. Dans SSE, [DONE] signifie seulement que la transmission est terminée et ne peut pas masquer les événements d'erreur déjà apparus auparavant.

Le jeton API ne doit être conservé que côté serveur ; l'analyseur de flux doit pouvoir traiter les fragments réseau et les nouveaux événements temporairement inconnus ; les appels d'outils doivent être appariés selon tool_id ; les liens de citation et les artefacts doivent être affichés de manière sécurisée ; les connexions avec capacité d'écriture doivent continuer à conserver une confirmation humaine ou une autorisation sans surveillance suffisamment limitée. Les noms de modèles, la facturation et les capacités disponibles peuvent évoluer ; lors de l'intégration officielle, il faut se référer à la documentation actuelle, à la page de service et à la console, sans figer durablement les configurations d'exemple.

L'aspect le plus intéressant d'AI Chat v2 n'est pas d'ajouter quelques boutons supplémentaires à la fenêtre de chat. Il permet enfin aux applications de voir ce qui se passe à l'intérieur d'une tâche IA : quand le modèle génère du texte, quand il appelle des outils, où il attend l'utilisateur et dans quel état il se termine.

Si le projet existant n'est encore qu'une interface ordinaire de questions-réponses, vous pouvez d'abord modifier l'adresse de l'interface et continuer à utiliser le corps de requête d'origine. Une fois cette étape stabilisée, intégrez ensuite message, NDJSON ou SSE, la chronologie des outils et la reprise après pause. La mise à niveau peut être minime, mais elle laisse suffisamment d'espace pour les futures formes du produit.

Liens de référence