Artikelbeschreibung: AI Chat v2 behält die einfache Aufrufweise der ursprünglichen Gesprächsschnittstelle bei und ergänzt gleichzeitig multimodale Eingaben, strukturierte Ereignisströme, automatische Tool-Aufrufe, Pausieren und Fortsetzen, asynchrone Ausführung und Sitzungsverwaltung. Dieser Artikel beginnt mit einer Migration, die nahezu keine Code-Neuschreibung erfordert, und erklärt, wie diese Änderungen die reale Produktentwicklung beeinflussen.
Viele Chat-Schnittstellen funktionieren in der Demonstrationsphase sehr gut: Eine Frage wird übergeben, auf die Rückgabe eines Textabschnitts durch das Modell gewartet und der Text anschließend auf der Seite angezeigt.
Wenn das Produkt weiterentwickelt wird, geht es nicht mehr nur um „eine Frage stellen, eine Antwort erhalten“. Nutzer laden PDFs und Screenshots hoch, das Modell muss Webseiten durchsuchen, Dateien lesen und sogar bereits autorisierte Tools wie GitHub und Notion aufrufen. Eine Aufgabe kann mehrere Runden dauern und zwischendurch wegen fehlender Informationen anhalten, um Rückfragen zu stellen. Wenn die Schnittstelle zu diesem Zeitpunkt weiterhin nur eine stetig wachsende Textzeichenfolge zurückgibt, kann das Frontend nur schwer erkennen, was das Modell gerade tut, und das Backend kann ebenfalls nur schwer feststellen, ob die Aufgabe tatsächlich beendet ist.
Die Ace Data Cloud AI Chat v2 API löst genau dieses Problem. Sie verwirft die ursprüngliche Gesprächsweise nicht, sondern zerlegt eine Antwort auf Grundlage der Kompatibilität mit einfachen Aufrufen in Ereignisse, die Programme erkennen und verarbeiten können: Fließtext ist Fließtext, Tool-Aufrufe sind Tool-Aufrufe, und Zitate, Dateien, Fehler und der endgültige Status haben jeweils eine klar definierte Position.

Abbildung: AI Chat v2 komprimiert nicht mehr die gesamte Aufgabe zu einem Textabschnitt, sondern bewahrt die Struktur von Eingaben, Tools und Ausgabeereignissen.
¶ Die Migration kann zunächst mit der Änderung einer Adresse beginnen
Wenn ein Projekt die ältere Version /aichat/conversations verwendet, müssen weder zuerst die Nachrichtenstruktur neu geschrieben noch zuerst eine Agent-Oberfläche erstellt werden. V2 akzeptiert weiterhin die bisherigen Felder wie model, question, stateful, id, references und preset. Für die minimale Migration muss nur die Anfrageadresse geändert werden zu:
https://api.acedata.cloud/aichat2/conversations
Eine grundlegendste Anfrage bleibt weiterhin sehr kurz:
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
}'
Im normalen JSON-Modus gibt die Schnittstelle weiterhin das vertraute Ergebnis zurück:
{
"answer": "...",
"id": "conversation-uuid"
}
Speichern Sie die zurückgegebene id; wenn bei der nächsten Anfrage dieselbe id mitgegeben wird, kann das Gespräch fortgesetzt werden. stateful ist standardmäßig true und steuert, ob der Kontext einer gespeicherten Sitzung geladen und fortgeführt wird.
Dieser Schritt eignet sich sehr gut für reale Projekte: Zuerst prüfen, ob Authentifizierung, Modell, Latenz und das bestehende Geschäft normal funktionieren, und anschließend schrittweise neue Funktionen integrieren. Die Migration muss nicht gemeinsam mit einem Oberflächen-Refactoring in derselben Veröffentlichung erfolgen.
¶ Wenn Dateien und Bilder in das Gespräch eintreten, wird auch die Reihenfolge zu Information
Die bisherige question eignet sich für reinen Text. Bei Aufgaben wie „zuerst den Bericht ansehen, dann mit dem Screenshot vergleichen und schließlich eine Schlussfolgerung ziehen“ reicht eine einfache Anhangsliste nicht mehr präzise aus. V2 ergänzt ein strukturiertes message-Array, in das Text, Bilder und Dateien in Reihenfolge eingefügt werden können:
{
"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"}
}
]
}
Verfügbare Inhaltsblöcke umfassen text, image_url und file_url. Wichtig ist nicht nur, dass „Anhänge unterstützt werden“, sondern dass die Beziehungen zwischen den Inhalten bei der Übertragung nicht verloren gehen. Der Client kann dem Modell eindeutig mitteilen: Welcher Abschnitt ist die Aufgabenbeschreibung, welches Dokument ist das Ausgangsmaterial und was soll anschließend verglichen werden.
Um älteren Clients eine reibungslose Migration zu ermöglichen, erkennt V2 weiterhin references. URLs mit Bilddateierweiterungen werden als Bilder behandelt, andere URLs als Dateien. Wenn nur die Schnittstelle aktualisiert wird, kann die bisherige Schreibweise vorübergehend beibehalten werden; wenn die Eingabereihenfolge das Verständnis beeinflusst, wird empfohlen, message zu verwenden.
¶ Streaming-Antworten bestehen nicht mehr nur aus „Tippen läuft“
Traditionelle Streaming-Ausgaben enthalten gewöhnlich nur Textinkremente. Wenn das Modell mit der Suche beginnt, Dateien liest oder externe Tools aufruft, wirkt die Seite wie eingefroren; Nutzer wissen nicht, ob die Aufgabe fortgesetzt wird, und Entwickler erhalten ebenfalls keinen klaren Status.
AI Chat v2 bietet über den Anfrage-Header accept drei Antwortarten:
| Anwendungsszenario | accept |
Rückgabeart |
|---|---|---|
| Einfache serverseitige Anfrage | application/json |
Nach Abschluss Rückgabe von {answer, id} |
| Node, Python, CLI oder Worker | application/x-ndjson |
Eine JSON-Ereignis pro Zeile |
| Web-Frontend | text/event-stream |
SSE-Ereignisstrom |
Im NDJSON- und SSE-Modus werden nicht nur Tokens zurückgegeben, sondern eine Gruppe typisierter Ereignisse. text_delta wird für Textinkremente verwendet, tool_use zeigt an, dass das Modell ein Tool aufzurufen vorbereitet, tool_result gibt das Tool-Ergebnis zurück, citation stellt Zitierquellen bereit, card und artifact tragen separat darstellbare Karten oder Ergebnisse, error zeigt das Fehlschlagen dieser Runde an und done liefert Nutzung und Beendigungsgrund.
Der folgende Python-Consumer setzt während der Text zusammengesetzt wird gleichzeitig wichtige Statusinformationen fort:
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))
Wenn das Produkt nur den endgültigen Text benötigt, genügt es, alle text_delta.content zusammenzufügen; wenn eine beobachtbare Agent-Oberfläche erstellt werden soll, können Tool-Aufrufe, Quellenangaben, Ergebnisse und Zustände jeweils separat dargestellt werden. Beide Anforderungen verwenden dieselbe Schnittstelle, sodass nicht für „einfachen Chat“ und „komplexe Aufgaben“ zwei Protokollsätze gepflegt werden müssen.
¶ Tool-Aufrufe sind standardmäßig verfügbar, aber das Produkt muss weiterhin klare Grenzen ziehen
V2 kann das Modell je nach Aufgabenbedarf integrierte Fähigkeiten wie Websuche, Seitenextraktion und Dateilesen aufrufen lassen; nachdem Benutzer entsprechende Dienste verbunden und autorisiert haben, können auch MCP-Tools zur Verarbeitung externer Daten wie GitHub und Notion verwendet werden.
Im Stream erscheinen jeweils tool_use und tool_result, die über tool_id zugeordnet werden. Das Frontend kann darauf basierend den tatsächlichen Fortschritt anzeigen, und das Backend kann außerdem die Dauer jedes Tools und die Fehlerstellen aufzeichnen.
Dass Tools automatisch aufgerufen werden können, bedeutet nicht, dass der Ausführungsumfang unbegrenzt freigegeben werden sollte. max_turns dient dazu, die Anzahl der Agent-Iterationsrunden in einer Anfrage zu begrenzen; der in der Dokumentation angegebene Bereich liegt bei 1—500; bei der Einstellung 1 wird in dieser Runde nur ein Modellaufruf ausgeführt und nicht weiter in Tool-Aufrufe übergegangen. In Produktionsumgebungen sollte dies aktiv anhand der Aufgabenkomplexität, Antwortzeit und des Kostenbudgets festgelegt werden, anstatt sich langfristig auf ein großes Standardlimit zu verlassen.
Für Webhook-, CI/CD- oder Überwachungsaufgaben unterstützt V2 async: true; Aufgaben können im Hintergrund ausgeführt und die Ergebnisse über Abfragen oder callback_url abgerufen werden. Aktionen, die Senden, Veröffentlichen oder Schreiben betreffen, müssen jedoch über allowed_skills, allowed_mcp_servers oder unattended_policy ausdrücklich vorautorisiert werden.
Verbindungen lösen die Frage „ob zugegriffen werden kann“, Autorisierungsrichtlinien lösen die Frage „ob bei diesem Mal im Namen des Benutzers gehandelt werden darf“. Diese beiden Dinge dürfen nicht vermischt werden.
¶ Wenn dem Agent Informationen fehlen, muss nicht so getan werden, als sei die Aufgabe bereits abgeschlossen
Komplexe Aufgaben geraten häufig bei konkreten Fragen ins Stocken: In welchem Kanal soll veröffentlicht werden, welches Format soll verwendet werden, ob vorhandene Dateien überschrieben werden sollen. V2 bietet hierfür das Ereignis ask_user_question. Nach Auftreten des Ereignisses wechselt die Sitzung in den Zustand, auf Benutzereingaben zu warten.
Der Client speichert die id der aktuellen Sitzung und die entsprechende tool_id, zeigt die Frage an und sammelt die Antwort, gibt sie dann mit derselben Sitzungs-id über tool_results zurück, und die Aufgabe kann am Unterbrechungspunkt fortgesetzt werden. Dieser Mechanismus eignet sich auch für Genehmigungsknoten. Statt das Modell bei unzureichenden Informationen selbst raten zu lassen, sollten die fehlenden Entscheidungen an den Benutzer zurückgegeben werden.
¶ Auch die Sitzung selbst kann verwaltet werden
V2 fügt am selben Endpunkt leichtgewichtiges Sitzungs-CRUD hinzu und unterscheidet über action zwischen retrieve, retrieve_batch, update und delete.
retrieve_batch gibt Zusammenfassungen zurück, enthält jedoch keine vollständigen messages und eignet sich für die Sitzungsseitenleiste; wenn Benutzer die Sitzung tatsächlich öffnen, wird anschließend retrieve aufgerufen, um den Haupttext zu lesen. Bei langen Sitzungen überschreibt auch die serverseitige Kontextaufbereitung die gespeicherten ursprünglichen Nachrichten nicht durch Zusammenfassungen. Wenn weiterhin Artikel geändert, Zahlen überprüft oder Veröffentlichungen vorbereitet werden müssen, sollte nach wie vor der Originaltext gelesen werden, anstatt Zusammenfassungen als Ersatz für den Haupttext zu verwenden.
¶ Vor dem Go-live nicht nur prüfen, „ob Text zurückkommt“
Nach der Anbindung einer Agent-Schnittstelle bedeutet der Empfang von Teiltext nicht, dass diese Runde bereits zuverlässig abgeschlossen ist; auch das Ende des Streams bedeutet nicht unbedingt, dass die Aufgabe erfolgreich war. Der Client sollte error verarbeiten und nach dem Empfang von done usage und terminal_reason aufzeichnen. In SSE zeigt [DONE] nur das Ende der Übertragung an und kann zuvor bereits aufgetretene Fehlerereignisse nicht aufheben.
API-Tokens sollten nur auf dem Server gespeichert werden; der Stream-Parser muss Netzwerkfragmentierung und vorübergehend unbekannte neue Ereignisse verarbeiten können; Tool-Aufrufe sollten über tool_id zugeordnet werden; Quellenlinks und Ergebnisse müssen sicher gerendert werden; beschreibbare Verbindungen sollten weiterhin eine menschliche Bestätigung oder eine ausreichend eng gefasste unbeaufsichtigte Autorisierung beibehalten. Modellnamen, Abrechnung und verfügbare Fähigkeiten können aktualisiert werden; bei der offiziellen Integration sollten die aktuelle Dokumentation, die Serviceseite und die Konsole maßgeblich sein, und Beispielkonfigurationen sollten nicht langfristig fest kodiert werden.
Das Bemerkenswerteste an AI Chat v2 ist nicht, dem Chatfenster noch ein paar weitere Schaltflächen hinzuzufügen. Es ermöglicht Anwendungen endlich zu sehen, was innerhalb einer KI-Aufgabe geschieht: wann das Modell Text ausgibt, wann es Tools aufruft, wo es auf den Benutzer wartet und mit welchem Status es endet.
Wenn das bestehende Projekt bisher nur ein gewöhnliches Frage-Antwort-Feld ist, kann zunächst die Schnittstellenadresse geändert und der ursprüngliche Request-Body weiterverwendet werden. Nachdem dieser Schritt stabil ist, können message, NDJSON oder SSE, die Tool-Zeitleiste und das Anhalten und Fortsetzen integriert werden. Das Upgrade kann klein sein, lässt jedoch ausreichend großen Raum für die späteren Produktformen.
