接入指南)
TEN Agent 集成 Coze 大模型coze_llm2_python 擴展源碼解析與實戰(zhàn)接入指南【免費下載鏈接】ten-frameworkOpen-source framework for conversational voice AI agents項目地址: https://gitcode.com/TEN-framework/ten-framework導(dǎo)讀coze_llm2_python是 TEN AgentTEN-framework中用于對接 Coze扣子Bot 服務(wù)的 Python LLM 擴展它將 Coze 的/v3/chat流式對話接口封裝為 TEN 標(biāo)準(zhǔn)的 LLM2 擴展接口讓開發(fā)者可以在語音 Agent 的圖graph中像使用其他 LLM 一樣直接掛載 Coze Bot。本文以 coze_llm2_python/README.md 為主體結(jié)合包內(nèi)源碼、清單與演示應(yīng)用配置講解該擴展的配置參數(shù)、消息流、流式解析原理、錯誤處理以及如何在真實 TEN Agent 應(yīng)用中完成接入。一、擴展概覽Coze 服務(wù)如何接入 TEN該擴展是 Coze 服務(wù)Coze / Coze China / 自建 Coze 兼容端點的 Python 實現(xiàn)其定位與openai_llm2_python、dify_llm2_python、anthropic_llm2_python等同類擴展一致統(tǒng)一實現(xiàn)AsyncLLM2BaseExtensionten_ai_base提供的 LLM2 基類從而在 TEN 的消息圖上以標(biāo)準(zhǔn) LLM 節(jié)點身份工作。README 中該包的自述標(biāo)題仍是coze_python_async而包的實際名稱已演進為coze_llm2_python見 manifest.json 中的name: coze_llm2_python版本0.2.1閱讀時需要注意這一命名差異。1.1 包結(jié)構(gòu)一覽文件作用manifest.json擴展聲明依賴ten_runtime_python 0.11與ten_ai_base 0.7導(dǎo)入 LLM2 接口定義聲明屬性 Schemaproperty.json默認配置支持${env:XXX}環(huán)境變量注入addon.pyAddon 入口注冊coze_llm2_python擴展并創(chuàng)建實例extension.py擴展主體生命周期管理、配置加載、LLM2 回調(diào)實現(xiàn)coze.pyCoze 客戶端aiohttp 會話、SSE 流式解析、錯誤處理requirements.txt / pyproject.toml依賴聲明cozepy0.6.2Python 版本要求3.101.2 核心能力流式對話將 TEN 的LLMRequest映射為 Coze/v3/chat的stream: true請求并把 Coze 的 SSE 事件流反向翻譯為 TEN 的LLMResponseMessageDelta/LLMResponseMessageDone流式響應(yīng)。多輪歷史通過additional_messages字段把請求中的歷史消息回傳給 CozeREADME 中描述為按max_history數(shù)量記錄歷史當(dāng)前實現(xiàn)的開關(guān)是auto_save_history見下文配置項差異說明。Bearer 認證使用Authorization: Bearer token請求頭完成默認鑒權(quán)。flush 支持README 明確說明擴展支持 flush 信號——收到 flush 后關(guān)閉當(dāng)前存在的 HTTP 會話對應(yīng)CozeChatClient.aclose()中的aiohttp.ClientSession.close()用于打斷或重置連接。二、配置參數(shù)詳解從 manifest 到運行時2.1 屬性 Schemamanifest.jsonmanifest.json 在api.property.properties中聲明了 4 個字符串屬性這是 TEN 框架校驗擴展配置的依據(jù)property: { properties: { base_url: { type: string }, bot_id: { type: string }, token: { type: string }, user_id: { type: string } } }同時該擴展通過import_uri: ../../system/ten_ai_base/api/llm-interface.json導(dǎo)入ten_ai_base系統(tǒng)包的 LLM2 接口定義表明它對外暴露的是標(biāo)準(zhǔn) LLM 消息接口該接口文件屬于 tman 安裝的系統(tǒng)包不隨本倉庫源碼分發(fā)。2.2 默認配置property.jsonproperty.json 給出的默認值為{ token: ${env:COZE_TOKEN}, bot_id: ${env:COZE_BOT_ID}, base_url: https://api.coze.com }可見token與bot_id采用${env:COZE_TOKEN}、${env:COZE_BOT_ID}形式從環(huán)境變量注入base_url固定指向國際版 Coze 端點https://api.coze.com。需要對接國內(nèi)版https://api.coze.cn或自建兼容端點時只需在應(yīng)用配置中覆蓋base_url即可。2.3 運行時配置結(jié)構(gòu)coze.pycoze.py 中CozeLLM2ConfigPydantic 模型定義了擴展實際解析的全部字段與默認值dataclass class CozeLLM2Config(BaseModel): base_url: str https://api.acoze.com bot_id: str token: str user_id: str TenAgent connect_timeout_s: float 15.0 total_timeout_s: float 90.0 auto_save_history: bool True各字段含義字段類型默認值說明base_urlstrhttps://api.acoze.comCoze 服務(wù)地址最終請求 URL 為{base_url}/v3/chatbot_idstrCoze Bot 的 ID必填項tokenstrCoze API Token用于Bearer鑒權(quán)必填項user_idstrTenAgent傳給 Coze 的用戶標(biāo)識Coze 側(cè)用于會話隔離與數(shù)據(jù)統(tǒng)計connect_timeout_sfloat15.0aiohttp 連接超時秒total_timeout_sfloat90.0aiohttp 整體請求超時秒auto_save_historyboolTrue是否讓 Coze 自動保存會話歷史配置項差異說明README 中提到的必填項寫作api_url而當(dāng)前 manifest 與源碼中的實際屬性名為base_urlREADME 提到的歷史條數(shù)參數(shù)max_history在實現(xiàn)中對應(yīng)為auto_save_history布爾開關(guān)。以源碼與 manifest 為準(zhǔn)配置base_url、bot_id、token即可運行user_id與超時參數(shù)均有合理默認值。2.4 配置加載與校驗extension.pyextension.py 在on_start中一次性讀取擴展的全部 property 并校驗async def on_start(self, async_ten_env: AsyncTenEnv) - None: async_ten_env.log_info(on_start) await super().on_start(async_ten_env) cfg_json, _ await self.ten_env.get_property_to_json() self.config CozeLLM2Config.model_validate_json(cfg_json) if not self.config.bot_id or not self.config.token: async_ten_env.log_info(Missing bot_id or token, exiting on_start) return try: self.client CozeChatClient(async_ten_env, self.config) ...關(guān)鍵點get_property_to_json()拉取擴展的完整 JSON 配置再交給 Pydantic 校驗bot_id或token缺失時只是記錄日志并提前退出on_start不會拋出異常導(dǎo)致整個應(yīng)用崩潰。這也呼應(yīng)了 README 中 token(must have) 的說明——實際表現(xiàn)為缺失則擴展不初始化客戶端。三、消息流與 LLM2 接口README 的 API 章節(jié)給出了擴展的輸入輸出契約Intext_data[data]ASR語音識別結(jié)果文本作為用戶消息進入 LLMflush[cmd]flush 信號用于打斷當(dāng)前會話/關(guān)閉 HTTP 連接。Outflush[cmd]flush 信號向下游如 TTS傳播打斷指令。運行時層面由于實現(xiàn)了AsyncLLM2BaseExtension擴展內(nèi)部實際消費的是LLMRequest含messages列表產(chǎn)出的是LLMResponseMessageDelta增量與LLMResponseMessageDone結(jié)束兩類流式響應(yīng)。on_retrieve_prompt在 extension.py 中被實現(xiàn)為返回空字符串并注釋說明 Coze doesnt use system prompts——Coze 的系統(tǒng)提示詞在 Bot 控制臺配置不走 TEN 的 prompt 檢索鏈路。四、核心實現(xiàn)原理CozeChatClient 源碼級拆解4.1 HTTP 會話與認證CozeChatClient使用aiohttp.ClientSession管理連接會話在首次請求時惰性創(chuàng)建并應(yīng)用connect_timeout_s默認 15s與total_timeout_s默認 90s兩個超時timeout aiohttp.ClientTimeout( connectself.config.connect_timeout_s, totalself.config.total_timeout_s, ) self._session aiohttp.ClientSession(timeouttimeout)每個請求都攜帶Authorization: Bearer {token}對應(yīng) README 的 use Bearer token to support default auth。aclose()負責(zé)關(guān)閉會話并置空引用供on_stop與 flush 場景調(diào)用。4.2 消息映射LLMRequest → Coze additional_messages_build_additional_messages將 TEN 的LLMRequest.messages映射為 Coze 的additional_messages簡單文本消息中user角色轉(zhuǎn)換為Message.build_user_question_text(content)assistant角色轉(zhuǎn)換為Message.build_assistant_answer(content)多模態(tài)的 list 內(nèi)容如音視頻分段則退化為拼接其中的text字段作為純文本消息無法提取文本的分段會被跳過。4.3 請求體與流式解析核心請求在get_chat_completions中構(gòu)造并 POST 到{base_url}/v3/chatpayload { bot_id: self.config.bot_id, user_id: self.config.user_id, additional_messages: additional_messages, stream: True, auto_save_history: self.config.auto_save_history, }響應(yīng)采用 SSEServer-Sent Events逐行讀取解析邏輯位于 coze.pyevent:行記錄當(dāng)前事件類型遇到done直接終止讀取data:行是 JSON 載荷交由_event_to_chatevent通過cozepy的ChatEvent/Message/Chat模型解析CONVERSATION_MESSAGE_DELTA事件提取message.content增量累加到full_content后以LLMResponseMessageDelta產(chǎn)出content為累計全文、delta為本次增量CONVERSATION_MESSAGE_COMPLETED為無操作事件流結(jié)束后統(tǒng)一發(fā)出LLMResponseMessageDone作為終止消息非 SSE 格式的 JSON 響應(yīng)視為錯誤信封code 4000表示 Coze bot is not publishedBot 未發(fā)布。4.4 錯誤處理可操作的失敗提示擴展對兩類高頻錯誤給出了明確提示CONVERSATION_CHAT_FAILED事件中l(wèi)ast_error.code 4011時拋出RuntimeError(The Coze token has been depleted. Please check your token usage.)——Token 額度耗盡錯誤信封code 4000時拋出RuntimeError(Coze bot is not published.)——Bot 未發(fā)布需要先在 Coze 控制臺發(fā)布。這兩條信息在實際排障中非常有用前者提示檢查/續(xù)費 Token后者提示回 Coze 控制臺完成發(fā)布流程。五、實戰(zhàn)接入在 TEN Agent 應(yīng)用中掛載 Coze LLM倉庫自帶的演示應(yīng)用demo已包含一個完整的 Coze 語音 Agent 圖va_coze_azure可直接作為接入模板見 demo/tenapp/property.json。5.1 聲明依賴應(yīng)用 manifest.json 通過本地路徑聲明依賴{ path: ../../../ten_packages/extension/coze_llm2_python }5.2 圖中配置 LLM 節(jié)點在va_coze_azure圖中LLM 節(jié)點配置如下節(jié)選{ type: extension, name: llm, addon: coze_llm2_python, extension_group: chatgpt, property: { token: ${env:COZE_TOKEN}, bot_id: ${env:COZE_BOT_ID}, base_url: https://api.coze.com } }該圖同時串聯(lián)了 RTC 音頻輸入agora_rtc、ASRazure_asr_python將識別文本送入llm節(jié)點即 README 中的text_data輸入與 TTSazure_tts_python構(gòu)成完整的語音輸入 → 識別 → Coze Bot 對話 → 語音合成鏈路。接入步驟歸納在 Coze 平臺創(chuàng)建并發(fā)布Bot取得BOT_ID生成 API Token 作為TOKEN在應(yīng)用 property 中為llm節(jié)點指定addon: coze_llm2_python并設(shè)置token/bot_id/base_url默認https://api.coze.com國內(nèi)版改https://api.coze.cn在啟動環(huán)境導(dǎo)出環(huán)境變量export COZE_TOKEN... export COZE_BOT_ID...運行應(yīng)用將 ASR 節(jié)點的輸出連接到llm節(jié)點輸入。5.3 運行 README 中的示例包裝服務(wù)README 附帶了一個 OpenAI 兼容包裝服務(wù)的示例說明對應(yīng)examples/openai_wrapper.py用于把 Coze 以 OpenAI 風(fēng)格接口暴露給外部調(diào)用方默認監(jiān)聽 8000 端口export API_TOKENxxx export OPENAI_API_KEYxxx python3 openai_wrapper.py啟動后預(yù)期輸出INFO: Started server process [162886] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRLC to quit)說明README 引用的schema.yml與examples/openai_wrapper.py屬于文檔描述的附件當(dāng)前倉庫快照中未隨包分發(fā)示例命令與端口信息以 README 為準(zhǔn)。API_TOKEN對應(yīng) Coze TokenOPENAI_API_KEY對應(yīng)包裝層向調(diào)用方暴露的密鑰。六、生命周期與資源管理擴展完整實現(xiàn)了 TEN 擴展的生命周期回調(diào)extension.py回調(diào)行為on_init記錄日志調(diào)用基類初始化on_start加載配置、校驗bot_id/token、創(chuàng)建CozeChatClienton_stop調(diào)用client.aclose()關(guān)閉 aiohttp 會話再執(zhí)行基類收尾on_deinit記錄日志調(diào)用基類反初始化會話的生命周期集中在CozeChatClient上_ensure_session()在會話為空或已關(guān)閉時按配置重建aclose()關(guān)閉并置空會話。這正是 README 所述 The extension support flush that will close the existing http session 的落地實現(xiàn)——flush 語義通過關(guān)閉底層 HTTP 會話實現(xiàn)連接中斷后續(xù)請求會由_ensure_session自動重建新會話。七、常見問題排查清單現(xiàn)象可能原因處理方式啟動日志出現(xiàn)Missing bot_id or token, exiting on_start未配置token/bot_id或環(huán)境變量未注入檢查${env:COZE_TOKEN}/${env:COZE_BOT_ID}是否導(dǎo)出或直接在 property 中寫入明文值報錯The Coze token has been depletedToken 額度耗盡Coze 錯誤碼 4011檢查 Coze 控制臺 Token 用量并續(xù)費/更換 Token報錯Coze bot is not publishedBot 未發(fā)布錯誤碼 4000到 Coze 控制臺完成 Bot 發(fā)布報錯chat failed且 HTTP 狀態(tài)非 200base_url指向錯誤、Token 無效或網(wǎng)絡(luò)不可達核對base_url國際api.coze.com/ 國內(nèi)api.coze.cn、Token 有效性并檢查connect_timeout_s/total_timeout_s是否過短長時間無響應(yīng)后超時默認整體超時 90s 觸發(fā)按需調(diào)大total_timeout_s結(jié)語coze_llm2_python是一個小而完整的 LLM2 擴展范本通過 manifest 聲明接口、property 提供默認值、Pydantic 承載配置、aiohttp 承載流式傳輸、cozepy承載事件模型最終以標(biāo)準(zhǔn)LLMResponseMessageDelta/LLMResponseMessageDone融入 TEN 的圖執(zhí)行體系。讀者既可以直接在語音 Agent 應(yīng)用中掛載 Coze Bot也可以對照 extension.py 與 coze.py 的代碼理解外部 LLM 服務(wù)如何接入 TEN的完整模式并遷移到其他服務(wù)OpenAI、Anthropic、Dify 等的同類擴展實現(xiàn)中。【免費下載鏈接】ten-frameworkOpen-source framework for conversational voice AI agents項目地址: https://gitcode.com/TEN-framework/ten-framework創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 TEN Agent 集成 Coze 大模型：coze_llm2_python 擴展源碼解析與實戰(zhàn)接入指南
TEN Agent 集成 Coze 大模型coze_llm2_python 擴展源碼解析與實戰(zhàn)接入指南【免費下載鏈接】ten-frameworkOpen-source framework for conversational voice AI agents項目地址: https://gitcode.com/TEN-framework/ten-framework導(dǎo)讀coze_llm2_python是 TEN AgentTEN-framework中用于對接 Coze扣子Bot 服務(wù)的 Python LLM 擴展它將 Coze 的/v3/chat流式對話接口封裝為 TEN 標(biāo)準(zhǔn)的 LLM2 擴展接口讓開發(fā)者可以在語音 Agent 的圖graph中像使用其他 LLM 一樣直接掛載 Coze Bot。本文以 coze_llm2_python/README.md 為主體結(jié)合包內(nèi)源碼、清單與演示應(yīng)用配置講解該擴展的配置參數(shù)、消息流、流式解析原理、錯誤處理以及如何在真實 TEN Agent 應(yīng)用中完成接入。一、擴展概覽Coze 服務(wù)如何接入 TEN該擴展是 Coze 服務(wù)Coze / Coze China / 自建 Coze 兼容端點的 Python 實現(xiàn)其定位與openai_llm2_python、dify_llm2_python、anthropic_llm2_python等同類擴展一致統(tǒng)一實現(xiàn)AsyncLLM2BaseExtensionten_ai_base提供的 LLM2 基類從而在 TEN 的消息圖上以標(biāo)準(zhǔn) LLM 節(jié)點身份工作。README 中該包的自述標(biāo)題仍是coze_python_async而包的實際名稱已演進為coze_llm2_python見 manifest.json 中的name: coze_llm2_python版本0.2.1閱讀時需要注意這一命名差異。1.1 包結(jié)構(gòu)一覽文件作用manifest.json擴展聲明依賴ten_runtime_python 0.11與ten_ai_base 0.7導(dǎo)入 LLM2 接口定義聲明屬性 Schemaproperty.json默認配置支持${env:XXX}環(huán)境變量注入addon.pyAddon 入口注冊coze_llm2_python擴展并創(chuàng)建實例extension.py擴展主體生命周期管理、配置加載、LLM2 回調(diào)實現(xiàn)coze.pyCoze 客戶端aiohttp 會話、SSE 流式解析、錯誤處理requirements.txt / pyproject.toml依賴聲明cozepy0.6.2Python 版本要求3.101.2 核心能力流式對話將 TEN 的LLMRequest映射為 Coze/v3/chat的stream: true請求并把 Coze 的 SSE 事件流反向翻譯為 TEN 的LLMResponseMessageDelta/LLMResponseMessageDone流式響應(yīng)。多輪歷史通過additional_messages字段把請求中的歷史消息回傳給 CozeREADME 中描述為按max_history數(shù)量記錄歷史當(dāng)前實現(xiàn)的開關(guān)是auto_save_history見下文配置項差異說明。Bearer 認證使用Authorization: Bearer token請求頭完成默認鑒權(quán)。flush 支持README 明確說明擴展支持 flush 信號——收到 flush 后關(guān)閉當(dāng)前存在的 HTTP 會話對應(yīng)CozeChatClient.aclose()中的aiohttp.ClientSession.close()用于打斷或重置連接。二、配置參數(shù)詳解從 manifest 到運行時2.1 屬性 Schemamanifest.jsonmanifest.json 在api.property.properties中聲明了 4 個字符串屬性這是 TEN 框架校驗擴展配置的依據(jù)property: { properties: { base_url: { type: string }, bot_id: { type: string }, token: { type: string }, user_id: { type: string } } }同時該擴展通過import_uri: ../../system/ten_ai_base/api/llm-interface.json導(dǎo)入ten_ai_base系統(tǒng)包的 LLM2 接口定義表明它對外暴露的是標(biāo)準(zhǔn) LLM 消息接口該接口文件屬于 tman 安裝的系統(tǒng)包不隨本倉庫源碼分發(fā)。2.2 默認配置property.jsonproperty.json 給出的默認值為{ token: ${env:COZE_TOKEN}, bot_id: ${env:COZE_BOT_ID}, base_url: https://api.coze.com }可見token與bot_id采用${env:COZE_TOKEN}、${env:COZE_BOT_ID}形式從環(huán)境變量注入base_url固定指向國際版 Coze 端點https://api.coze.com。需要對接國內(nèi)版https://api.coze.cn或自建兼容端點時只需在應(yīng)用配置中覆蓋base_url即可。2.3 運行時配置結(jié)構(gòu)coze.pycoze.py 中CozeLLM2ConfigPydantic 模型定義了擴展實際解析的全部字段與默認值dataclass class CozeLLM2Config(BaseModel): base_url: str https://api.acoze.com bot_id: str token: str user_id: str TenAgent connect_timeout_s: float 15.0 total_timeout_s: float 90.0 auto_save_history: bool True各字段含義字段類型默認值說明base_urlstrhttps://api.acoze.comCoze 服務(wù)地址最終請求 URL 為{base_url}/v3/chatbot_idstrCoze Bot 的 ID必填項tokenstrCoze API Token用于Bearer鑒權(quán)必填項user_idstrTenAgent傳給 Coze 的用戶標(biāo)識Coze 側(cè)用于會話隔離與數(shù)據(jù)統(tǒng)計connect_timeout_sfloat15.0aiohttp 連接超時秒total_timeout_sfloat90.0aiohttp 整體請求超時秒auto_save_historyboolTrue是否讓 Coze 自動保存會話歷史配置項差異說明README 中提到的必填項寫作api_url而當(dāng)前 manifest 與源碼中的實際屬性名為base_urlREADME 提到的歷史條數(shù)參數(shù)max_history在實現(xiàn)中對應(yīng)為auto_save_history布爾開關(guān)。以源碼與 manifest 為準(zhǔn)配置base_url、bot_id、token即可運行user_id與超時參數(shù)均有合理默認值。2.4 配置加載與校驗extension.pyextension.py 在on_start中一次性讀取擴展的全部 property 并校驗async def on_start(self, async_ten_env: AsyncTenEnv) - None: async_ten_env.log_info(on_start) await super().on_start(async_ten_env) cfg_json, _ await self.ten_env.get_property_to_json() self.config CozeLLM2Config.model_validate_json(cfg_json) if not self.config.bot_id or not self.config.token: async_ten_env.log_info(Missing bot_id or token, exiting on_start) return try: self.client CozeChatClient(async_ten_env, self.config) ...關(guān)鍵點get_property_to_json()拉取擴展的完整 JSON 配置再交給 Pydantic 校驗bot_id或token缺失時只是記錄日志并提前退出on_start不會拋出異常導(dǎo)致整個應(yīng)用崩潰。這也呼應(yīng)了 README 中 token(must have) 的說明——實際表現(xiàn)為缺失則擴展不初始化客戶端。三、消息流與 LLM2 接口README 的 API 章節(jié)給出了擴展的輸入輸出契約Intext_data[data]ASR語音識別結(jié)果文本作為用戶消息進入 LLMflush[cmd]flush 信號用于打斷當(dāng)前會話/關(guān)閉 HTTP 連接。Outflush[cmd]flush 信號向下游如 TTS傳播打斷指令。運行時層面由于實現(xiàn)了AsyncLLM2BaseExtension擴展內(nèi)部實際消費的是LLMRequest含messages列表產(chǎn)出的是LLMResponseMessageDelta增量與LLMResponseMessageDone結(jié)束兩類流式響應(yīng)。on_retrieve_prompt在 extension.py 中被實現(xiàn)為返回空字符串并注釋說明 Coze doesnt use system prompts——Coze 的系統(tǒng)提示詞在 Bot 控制臺配置不走 TEN 的 prompt 檢索鏈路。四、核心實現(xiàn)原理CozeChatClient 源碼級拆解4.1 HTTP 會話與認證CozeChatClient使用aiohttp.ClientSession管理連接會話在首次請求時惰性創(chuàng)建并應(yīng)用connect_timeout_s默認 15s與total_timeout_s默認 90s兩個超時timeout aiohttp.ClientTimeout( connectself.config.connect_timeout_s, totalself.config.total_timeout_s, ) self._session aiohttp.ClientSession(timeouttimeout)每個請求都攜帶Authorization: Bearer {token}對應(yīng) README 的 use Bearer token to support default auth。aclose()負責(zé)關(guān)閉會話并置空引用供on_stop與 flush 場景調(diào)用。4.2 消息映射LLMRequest → Coze additional_messages_build_additional_messages將 TEN 的LLMRequest.messages映射為 Coze 的additional_messages簡單文本消息中user角色轉(zhuǎn)換為Message.build_user_question_text(content)assistant角色轉(zhuǎn)換為Message.build_assistant_answer(content)多模態(tài)的 list 內(nèi)容如音視頻分段則退化為拼接其中的text字段作為純文本消息無法提取文本的分段會被跳過。4.3 請求體與流式解析核心請求在get_chat_completions中構(gòu)造并 POST 到{base_url}/v3/chatpayload { bot_id: self.config.bot_id, user_id: self.config.user_id, additional_messages: additional_messages, stream: True, auto_save_history: self.config.auto_save_history, }響應(yīng)采用 SSEServer-Sent Events逐行讀取解析邏輯位于 coze.pyevent:行記錄當(dāng)前事件類型遇到done直接終止讀取data:行是 JSON 載荷交由_event_to_chatevent通過cozepy的ChatEvent/Message/Chat模型解析CONVERSATION_MESSAGE_DELTA事件提取message.content增量累加到full_content后以LLMResponseMessageDelta產(chǎn)出content為累計全文、delta為本次增量CONVERSATION_MESSAGE_COMPLETED為無操作事件流結(jié)束后統(tǒng)一發(fā)出LLMResponseMessageDone作為終止消息非 SSE 格式的 JSON 響應(yīng)視為錯誤信封code 4000表示 Coze bot is not publishedBot 未發(fā)布。4.4 錯誤處理可操作的失敗提示擴展對兩類高頻錯誤給出了明確提示CONVERSATION_CHAT_FAILED事件中l(wèi)ast_error.code 4011時拋出RuntimeError(The Coze token has been depleted. Please check your token usage.)——Token 額度耗盡錯誤信封code 4000時拋出RuntimeError(Coze bot is not published.)——Bot 未發(fā)布需要先在 Coze 控制臺發(fā)布。這兩條信息在實際排障中非常有用前者提示檢查/續(xù)費 Token后者提示回 Coze 控制臺完成發(fā)布流程。五、實戰(zhàn)接入在 TEN Agent 應(yīng)用中掛載 Coze LLM倉庫自帶的演示應(yīng)用demo已包含一個完整的 Coze 語音 Agent 圖va_coze_azure可直接作為接入模板見 demo/tenapp/property.json。5.1 聲明依賴應(yīng)用 manifest.json 通過本地路徑聲明依賴{ path: ../../../ten_packages/extension/coze_llm2_python }5.2 圖中配置 LLM 節(jié)點在va_coze_azure圖中LLM 節(jié)點配置如下節(jié)選{ type: extension, name: llm, addon: coze_llm2_python, extension_group: chatgpt, property: { token: ${env:COZE_TOKEN}, bot_id: ${env:COZE_BOT_ID}, base_url: https://api.coze.com } }該圖同時串聯(lián)了 RTC 音頻輸入agora_rtc、ASRazure_asr_python將識別文本送入llm節(jié)點即 README 中的text_data輸入與 TTSazure_tts_python構(gòu)成完整的語音輸入 → 識別 → Coze Bot 對話 → 語音合成鏈路。接入步驟歸納在 Coze 平臺創(chuàng)建并發(fā)布Bot取得BOT_ID生成 API Token 作為TOKEN在應(yīng)用 property 中為llm節(jié)點指定addon: coze_llm2_python并設(shè)置token/bot_id/base_url默認https://api.coze.com國內(nèi)版改https://api.coze.cn在啟動環(huán)境導(dǎo)出環(huán)境變量export COZE_TOKEN... export COZE_BOT_ID...運行應(yīng)用將 ASR 節(jié)點的輸出連接到llm節(jié)點輸入。5.3 運行 README 中的示例包裝服務(wù)README 附帶了一個 OpenAI 兼容包裝服務(wù)的示例說明對應(yīng)examples/openai_wrapper.py用于把 Coze 以 OpenAI 風(fēng)格接口暴露給外部調(diào)用方默認監(jiān)聽 8000 端口export API_TOKENxxx export OPENAI_API_KEYxxx python3 openai_wrapper.py啟動后預(yù)期輸出INFO: Started server process [162886] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRLC to quit)說明README 引用的schema.yml與examples/openai_wrapper.py屬于文檔描述的附件當(dāng)前倉庫快照中未隨包分發(fā)示例命令與端口信息以 README 為準(zhǔn)。API_TOKEN對應(yīng) Coze TokenOPENAI_API_KEY對應(yīng)包裝層向調(diào)用方暴露的密鑰。六、生命周期與資源管理擴展完整實現(xiàn)了 TEN 擴展的生命周期回調(diào)extension.py回調(diào)行為on_init記錄日志調(diào)用基類初始化on_start加載配置、校驗bot_id/token、創(chuàng)建CozeChatClienton_stop調(diào)用client.aclose()關(guān)閉 aiohttp 會話再執(zhí)行基類收尾on_deinit記錄日志調(diào)用基類反初始化會話的生命周期集中在CozeChatClient上_ensure_session()在會話為空或已關(guān)閉時按配置重建aclose()關(guān)閉并置空會話。這正是 README 所述 The extension support flush that will close the existing http session 的落地實現(xiàn)——flush 語義通過關(guān)閉底層 HTTP 會話實現(xiàn)連接中斷后續(xù)請求會由_ensure_session自動重建新會話。七、常見問題排查清單現(xiàn)象可能原因處理方式啟動日志出現(xiàn)Missing bot_id or token, exiting on_start未配置token/bot_id或環(huán)境變量未注入檢查${env:COZE_TOKEN}/${env:COZE_BOT_ID}是否導(dǎo)出或直接在 property 中寫入明文值報錯The Coze token has been depletedToken 額度耗盡Coze 錯誤碼 4011檢查 Coze 控制臺 Token 用量并續(xù)費/更換 Token報錯Coze bot is not publishedBot 未發(fā)布錯誤碼 4000到 Coze 控制臺完成 Bot 發(fā)布報錯chat failed且 HTTP 狀態(tài)非 200base_url指向錯誤、Token 無效或網(wǎng)絡(luò)不可達核對base_url國際api.coze.com/ 國內(nèi)api.coze.cn、Token 有效性并檢查connect_timeout_s/total_timeout_s是否過短長時間無響應(yīng)后超時默認整體超時 90s 觸發(fā)按需調(diào)大total_timeout_s結(jié)語coze_llm2_python是一個小而完整的 LLM2 擴展范本通過 manifest 聲明接口、property 提供默認值、Pydantic 承載配置、aiohttp 承載流式傳輸、cozepy承載事件模型最終以標(biāo)準(zhǔn)LLMResponseMessageDelta/LLMResponseMessageDone融入 TEN 的圖執(zhí)行體系。讀者既可以直接在語音 Agent 應(yīng)用中掛載 Coze Bot也可以對照 extension.py 與 coze.py 的代碼理解外部 LLM 服務(wù)如何接入 TEN的完整模式并遷移到其他服務(wù)OpenAI、Anthropic、Dify 等的同類擴展實現(xiàn)中。【免費下載鏈接】ten-frameworkOpen-source framework for conversational voice AI agents項目地址: https://gitcode.com/TEN-framework/ten-framework創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考