文章說明:AI Chat v2 保留原有對話介面的簡單呼叫方式,同時加入多模態輸入、結構化事件流、自動工具呼叫、暫停與恢復、非同步執行和工作階段管理。本文從一次幾乎不用重寫程式碼的遷移開始,講清楚這些變化如何影響真實的產品開發。

很多聊天介面在展示階段都很好用:傳入問題,等模型回傳一段文字,再把文字顯示在頁面上。

產品繼續往前走,事情就不再只是「問一句、答一句」。使用者會上傳 PDF 和截圖,模型需要查網頁、讀取檔案,甚至呼叫已經授權的 GitHub、Notion 等工具。一次任務可能持續好幾輪,中途還會因為缺少資訊停下來追問。此時,如果介面仍然只回傳一串不斷增長的文字,前端很難知道模型正在做什麼,後端也難以判斷任務究竟結束了沒有。

Ace Data Cloud AI Chat v2 API 解決的正是這個問題。它沒有推翻原來的對話方式,而是在相容簡單呼叫的基礎上,把一次回答拆成程式可以識別和處理的事件:正文是正文,工具呼叫是工具呼叫,引用、檔案、錯誤和最終狀態各自有明確的位置。

Ace Data Cloud AI Chat v2:多模態輸入、Agent 工具與結構化事件流

圖: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、工具時間軸和暫停恢復。升級可以很小,但它為後面的產品型態留出了足夠大的空間。

參考連結