文章說明:AI Chat v2 保留原有對話介面的簡單呼叫方式,同時加入多模態輸入、結構化事件流、自動工具呼叫、暫停與恢復、非同步執行和工作階段管理。本文從一次幾乎不用重寫程式碼的遷移開始,講清楚這些變化如何影響真實的產品開發。
很多聊天介面在展示階段都很好用:傳入問題,等模型回傳一段文字,再把文字顯示在頁面上。
產品繼續往前走,事情就不再只是「問一句、答一句」。使用者會上傳 PDF 和截圖,模型需要查網頁、讀取檔案,甚至呼叫已經授權的 GitHub、Notion 等工具。一次任務可能持續好幾輪,中途還會因為缺少資訊停下來追問。此時,如果介面仍然只回傳一串不斷增長的文字,前端很難知道模型正在做什麼,後端也難以判斷任務究竟結束了沒有。
Ace Data Cloud AI Chat v2 API 解決的正是這個問題。它沒有推翻原來的對話方式,而是在相容簡單呼叫的基礎上,把一次回答拆成程式可以識別和處理的事件:正文是正文,工具呼叫是工具呼叫,引用、檔案、錯誤和最終狀態各自有明確的位置。

圖:AI Chat v2 不再把整個任務壓成一段文字,而是讓輸入、工具和輸出事件保持結構。
¶ 遷移可以先從改一個位址開始
如果專案正在使用舊版 /aichat/conversations,不必先重寫訊息結構,也不用先做一套 Agent 介面。V2 繼續接受原有的 model、question、stateful、id、references 和 preset 等欄位。最小遷移只需要把請求位址改成:
https://api.acedata.cloud/aichat2/conversations
一個最基礎的請求仍然很短:
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
}'
普通 JSON 模式下,介面仍回傳熟悉的結果:
{
"answer": "...",
"id": "conversation-uuid"
}
儲存回傳的 id,下一次請求帶上同一個 id,便可以繼續對話。stateful 預設是 true,用於控制是否載入並延續已儲存工作階段的上下文。
這一步很適合真實專案:先驗證鑑權、模型、延遲和舊業務是否正常,再逐步接入新能力。遷移不必和介面重構綁在同一次上線裡。
¶ 當檔案和圖片進入對話,順序也成了資訊
舊版 question 適合純文字。到了「先看報告,再對照截圖,最後給結論」這種任務,簡單的附件列表就不夠精確了。V2 增加了結構化 message 陣列,可以依序放入文字、圖片和檔案:
{
"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"}
}
]
}
可用內容區塊包括 text、image_url 和 file_url。重要的並不只是「支援附件」,而是內容之間的關係沒有在傳輸時遺失。用戶端能夠明確告訴模型:哪一段是任務說明,哪一份是原始材料,接下來又該比較什麼。
為了讓舊用戶端平順遷移,V2 仍然識別 references。圖片副檔名對應的 URL 會按圖片處理,其他 URL 會按檔案處理。如果只是升級介面,可以暫時保留原寫法;如果輸入順序會影響理解,建議改用 message。
¶ 串流回應不再只有「正在打字」
傳統串流輸出通常只有文字增量。模型開始搜尋、讀取檔案或呼叫外部工具後,頁面看起來像卡住了,使用者不知道任務是否繼續,開發者也拿不到清楚的狀態。
AI Chat v2 透過 accept 請求標頭提供三種回應方式:
| 使用情境 | accept |
回傳方式 |
|---|---|---|
| 簡單伺服器端請求 | application/json |
完成後回傳 {answer, id} |
| Node、Python、CLI 或 Worker | application/x-ndjson |
每行一個 JSON 事件 |
| Web 前端 | text/event-stream |
SSE 事件流 |
在 NDJSON 和 SSE 模式中,回傳的不只是 token,而是一組有類型的事件。text_delta 用於正文增量,tool_use 表示模型準備呼叫工具,tool_result 回傳工具結果,citation 提供引用來源,card 和 artifact 承載可單獨展示的卡片或產物,error 表示本輪失敗,done 給出用量和終止原因。
下面的 Python 消費端一邊拼接正文,一邊保留關鍵狀態:
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))
如果產品只關心最終文字,把所有 text_delta.content 串接起來即可;如果要做可觀察的 Agent 介面,就可以把工具呼叫、引用、產物和狀態分別渲染。兩種需求使用同一個介面,不必為「簡單聊天」和「複雜任務」維護兩套協議。
¶ 工具呼叫預設可用,但產品仍要畫清界線
V2 可以讓模型依任務需要呼叫網頁搜尋、頁面擷取和檔案讀取等內建能力;使用者連線並授權相應服務後,也可以使用 MCP 工具處理 GitHub、Notion 等外部資料。
串流中會分別出現 tool_use 和 tool_result,兩者透過 tool_id 配對。前端可以據此顯示真實進度,後端也能記錄每次工具耗時和失敗位置。
工具能自動呼叫,並不意味著執行範圍應該無限放開。max_turns 用於約束一次請求中的 Agent 迭代輪數,文件給出的範圍是 1—500;設定為 1 時,本輪只進行一次模型呼叫,不會繼續進入工具呼叫。生產環境應結合任務複雜度、回應時間和成本預算主動設定,而不是長期依賴較大的預設上限。
對於 Webhook、CI/CD 或監控任務,V2 支援 async: true,任務可以在背景執行,並透過查詢或 callback_url 取得結果。但涉及傳送、發布、寫入的動作,需要透過 allowed_skills、allowed_mcp_servers 或 unattended_policy 明確預先授權。
連線解決的是「能不能存取」,授權策略解決的是「這一次可不可以代替使用者行動」。這兩件事不能混在一起。
¶ Agent 缺少資訊時,不必假裝任務已經完成
複雜任務經常卡在具體問題上:發布到哪個頻道、採用哪種格式、是否覆蓋已有檔案。V2 為此提供 ask_user_question 事件。事件出現後,會話進入等待使用者輸入的狀態。
用戶端儲存目前會話的 id 和對應 tool_id,顯示問題並收集答案,再用同一個會話 id,透過 tool_results 把回答交回去,任務便可以從暫停點繼續。這個機制也適合做審核節點。與其讓模型在資料不足時自行猜測,不如把缺失的選擇交還給使用者。
¶ 會話本身也可以管理
V2 在同一個端點中加入了輕量的會話 CRUD,透過 action 區分 retrieve、retrieve_batch、update 和 delete。
retrieve_batch 回傳摘要而不包含完整 messages,適合會話側邊欄;使用者真正開啟會話時,再呼叫 retrieve 讀取正文。對於長會話,伺服器端的上下文整理也不會用摘要覆蓋已儲存的原始訊息。需要繼續修改文章、核對數字或準備發布時,仍應讀取原文,而不是拿摘要代替正文。
¶ 上線前,別只驗證「有沒有文字回傳」
接入 Agent 介面之後,收到部分文字不等於本輪已經可靠完成;串流結束也不一定代表任務成功。用戶端應處理 error,並在收到 done 後記錄 usage 和 terminal_reason。在 SSE 中,[DONE] 只表示傳輸結束,不能覆蓋此前已經出現的錯誤事件。
API Token 應只保存在伺服器端;串流解析器要能處理網路分塊和暫時不認識的新事件;工具呼叫應依 tool_id 配對;引用連結和產物要安全渲染;可寫連線繼續保留人工確認或足夠窄的無人值守授權。模型名稱、計費與可用能力可能更新,正式接入時應以目前文件、服務頁和控制台為準,不要把範例設定長期寫死。
AI Chat v2 最值得關注的地方,並不是讓聊天視窗再多幾個按鈕。它讓應用程式終於能看見一次 AI 任務內部發生了什麼:模型何時輸出文字,何時呼叫工具,在哪裡等待使用者,又以什麼狀態結束。
如果現有專案還只是普通問答框,可以先改介面位址,繼續使用原來的請求主體。等這一步穩定後,再接入 message、NDJSON 或 SSE、工具時間軸和暫停恢復。升級可以很小,但它為後面的產品型態留出了足夠大的空間。
