集成監(jiān)控 LlamaIndex Agent：從安裝、初始化到事件采集原理)
使用 AgentOps 回調(diào)集成監(jiān)控 LlamaIndex Agent從安裝、初始化到事件采集原理【免費(fèi)下載鏈接】llama_indexLlamaIndex is the document processing platform for AI項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ll/llama_index導(dǎo)讀llama-index-callbacks-agentops是 LlamaIndex 官方回調(diào)Callback集成包它將 LlamaIndex 的 Agent 工作流與 AgentOps 可觀測(cè)平臺(tái)打通只需一行初始化代碼Agent 運(yùn)行過程中的 LLM 調(diào)用、工具調(diào)用與異常就會(huì)被自動(dòng)采集并上報(bào)到 AgentOps 儀表盤。讀完本文你將掌握該包的安裝方式、兩種初始化姿勢(shì)、init()全部可用參數(shù)以及事件采集的底層實(shí)現(xiàn)原理span/event 雙處理器架構(gòu)。安裝該包以獨(dú)立集成包的形式發(fā)布通過 pip 直接安裝pip install llama-index-callbacks-agentops從 pyproject.toml 可以看到它的依賴與約束agentops0.2.2,0.3底層 AgentOps Python SDKllama-index-core0.13.0,0.15依賴 LlamaIndex 核心庫提供的 instrumentation插樁框架要求Python 3.10,4.0當(dāng)前包版本為0.5.0采用 MIT 協(xié)議?？焖偕鲜謨煞N初始化方式方式一全局 Handler推薦利用llama_index.core提供的set_global_handler將 AgentOps 注冊(cè)為全局回調(diào)處理器from llama_index.core import set_global_handler set_global_handler(agentops, api_key...)在核心庫 global_handlers.py 中agentops分支會(huì)執(zhí)行懶加載——只有在調(diào)用時(shí)才從llama_index.callbacks.agentops導(dǎo)入AgentOpsHandler并執(zhí)行AgentOpsHandler.init(**eval_params)若包未安裝則拋出 ImportError 并提示安裝命令。這意味著api_key之外的所有關(guān)鍵字參數(shù)都可以通過set_global_handler原樣透?jìng)?。方式二直接初始?Handler如果你希望更顯式地控制處理器生命周期可以直接導(dǎo)入并初始化from llama_index.callbacks.agentops import AgentOpsHandler AgentOpsHandler.init(api_key...)該類的導(dǎo)出聲明位于init.py同時(shí)它也被注冊(cè)進(jìn) LlamaIndex 命令行映射見 mappings.json便于相關(guān)工具鏈識(shí)別。兩種方式底層走的是同一條路徑AgentOpsHandler.init()。init() 參數(shù)詳解根據(jù) base.py 中AgentOpsHandler.init()的方法簽名可用的關(guān)鍵字參數(shù)如下參數(shù)類型默認(rèn)值說明api_keyOptional[str]NoneAgentOps 平臺(tái) API Key用于身份認(rèn)證parent_keyOptional[str]None父級(jí) API KeyAgentOps 組織/賬戶層級(jí)擴(kuò)展場(chǎng)景endpointOptional[str]None自定義上報(bào)端點(diǎn)用于自托管 AgentOps 或代理環(huán)境max_wait_timeOptional[int]None事件批量上報(bào)的最大等待時(shí)間秒級(jí)max_queue_sizeOptional[int]None上報(bào)隊(duì)列的最大長(zhǎng)度超出后的處理策略由 AgentOps SDK 決定tagsOptional[List[str]]None附加到會(huì)話的標(biāo)簽列表便于在儀表盤按標(biāo)簽過濾instrument_llm_callsboolTrue是否由 AgentOps SDK 額外插樁 LLM 調(diào)用inherited_session_idOptional[str]None繼承已有會(huì)話 ID用于多進(jìn)程/多服務(wù)串聯(lián)同一會(huì)話init()內(nèi)部會(huì)將這些參數(shù)構(gòu)造為一個(gè)參數(shù)字典并過濾掉所有值為None的鍵后再傳給 AgentOps 的AOClient因此任何 AgentOpsAOClient支持的參數(shù)都可以沿用同名關(guān)鍵字透?jìng)鱎EADME 亦明確說明這一點(diǎn)。此外init()還強(qiáng)制注入了兩個(gè)會(huì)話行為參數(shù)auto_start_sessionTrue初始化后自動(dòng)開啟會(huì)話skip_auto_end_sessionFalse不跳過會(huì)話自動(dòng)結(jié)束邏輯即允許會(huì)話自動(dòng)結(jié)束。也就是說只要調(diào)用了init()AgentOps 會(huì)話生命周期管理會(huì)自動(dòng)開啟無需額外手動(dòng)調(diào)用。底層原理Span 與 Event 雙處理器架構(gòu)AgentOpsHandler繼承自核心庫的BaseInstrumentationHandler位于llama_index.core.instrumentation它本身不直接消費(fèi)事件而是在init()時(shí)從根 dispatcher 獲取分發(fā)器instrument.get_dispatcher()創(chuàng)建一對(duì)共享狀態(tài)的處理器并注冊(cè)AgentOpsSpanHandler繼承SimpleSpanHandler負(fù)責(zé) span 生命周期與異常關(guān)聯(lián)AgentOpsEventHandler繼承BaseEventHandler負(fù)責(zé)把 LlamaIndex 事件翻譯成 AgentOps 事件并調(diào)用ao_client.record()上報(bào)。兩者通過AgentOpsHandlerState一個(gè) Pydantic 模型共享運(yùn)行時(shí)狀態(tài)該狀態(tài)維護(hù)了四類映射span 是否源自 Agent 聊天is_agent_chat_span、Agent 聊天起始事件agent_chat_start_event、span 的父 spanspan_parent、span 內(nèi)拋出的異常集合span_exception。Span 處理器異常捕獲與上報(bào)AgentOpsSpanHandler在new_span時(shí)登記子 span 與父 span 的關(guān)聯(lián)在prepare_to_exit_span時(shí)清理狀態(tài)在prepare_to_drop_span時(shí)處理異常若當(dāng)前 span 因異常被丟棄先嘗試把異常關(guān)聯(lián)到父 span避免父 span 重復(fù)上報(bào)子 span 已記錄的異常若該異常尚未被記錄則調(diào)用self._ao_client.record(ErrorEvent(detailsstr(err)))上報(bào)為 AgentOps 的ErrorEvent。事件處理器LLM 與工具調(diào)用映射AgentOpsEventHandler.handle()只處理 Agent 場(chǎng)景下的事件核心映射邏輯如下AgentRunStepStartEvent標(biāo)記當(dāng)前 span 為 Agent 聊天 span觸發(fā)后續(xù)事件采集LLMChatStartEvent且處于 Agent 聊天 span 中緩存該事件的 span 關(guān)聯(lián)供結(jié)束事件回溯模型名LLMChatEndEvent且處于 Agent 聊天 span 中把消息列表轉(zhuǎn)換為{content, role}結(jié)構(gòu)作為prompt把響應(yīng)內(nèi)容作為completion并從response.raw[usage]中提取prompt_tokens/completion_tokens再通過get_chat_start_event()沿祖先 span 鏈回溯到對(duì)應(yīng)的 start 事件獲取model字段最終構(gòu)造LLMEvent上報(bào)AgentToolCallEvent將event.argumentsJSON 字符串反序列化為參數(shù)對(duì)象連同工具名構(gòu)造ToolEvent上報(bào)。其中check_is_agent_chat_span()會(huì)沿span_parent鏈遞歸檢查所有祖先 span判斷某個(gè)事件是否處于 Agent 運(yùn)行步驟之下get_chat_start_event()同樣沿祖先鏈尋找最近的LLMChatStartEvent。這正是只采集 Agent 場(chǎng)景下 LLM 調(diào)用這一設(shè)計(jì)意圖的實(shí)現(xiàn)細(xì)節(jié)。使用建議與注意事項(xiàng)Agent 場(chǎng)景限定從源碼可見普通非 Agent的 LLM 調(diào)用不會(huì)被采集——LLMChatEndEvent只有在is_agent_chat_event為真時(shí)才上報(bào)。若你的業(yè)務(wù)是純 RAG 問答而非 Agent 編排該集成可能無法覆蓋所有調(diào)用。異常自動(dòng)采集span 內(nèi)拋出的異常會(huì)自動(dòng)轉(zhuǎn)為ErrorEvent上報(bào)無需手動(dòng) try/except 包裝。版本配套包依賴llama-index-core0.13.0,0.15升級(jí) LlamaIndex 核心庫時(shí)請(qǐng)注意保持在該區(qū)間以免 instrumentation API 不兼容。自托管端點(diǎn)企業(yè)內(nèi)部部署 AgentOps 時(shí)通過endpoint參數(shù)指定上報(bào)地址即可。相關(guān)文件索引集成包 README官方安裝與初始化說明核心實(shí)現(xiàn) base.pyAgentOpsHandler、Span/Event 雙處理器與狀態(tài)模型包導(dǎo)出init.py公開 API 面包配置 pyproject.toml依賴與版本約束全局 Handler 注冊(cè)表set_global_handler(agentops, ...)的分發(fā)邏輯【免費(fèi)下載鏈接】llama_indexLlamaIndex is the document processing platform for AI項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ll/llama_index創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 使用 AgentOps 回調(diào)集成監(jiān)控 LlamaIndex Agent：從安裝、初始化到事件采集原理
使用 AgentOps 回調(diào)集成監(jiān)控 LlamaIndex Agent從安裝、初始化到事件采集原理【免費(fèi)下載鏈接】llama_indexLlamaIndex is the document processing platform for AI項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ll/llama_index導(dǎo)讀llama-index-callbacks-agentops是 LlamaIndex 官方回調(diào)Callback集成包它將 LlamaIndex 的 Agent 工作流與 AgentOps 可觀測(cè)平臺(tái)打通只需一行初始化代碼Agent 運(yùn)行過程中的 LLM 調(diào)用、工具調(diào)用與異常就會(huì)被自動(dòng)采集并上報(bào)到 AgentOps 儀表盤。讀完本文你將掌握該包的安裝方式、兩種初始化姿勢(shì)、init()全部可用參數(shù)以及事件采集的底層實(shí)現(xiàn)原理span/event 雙處理器架構(gòu)。安裝該包以獨(dú)立集成包的形式發(fā)布通過 pip 直接安裝pip install llama-index-callbacks-agentops從 pyproject.toml 可以看到它的依賴與約束agentops0.2.2,0.3底層 AgentOps Python SDKllama-index-core0.13.0,0.15依賴 LlamaIndex 核心庫提供的 instrumentation插樁框架要求Python 3.10,4.0當(dāng)前包版本為0.5.0采用 MIT 協(xié)議?？焖偕鲜謨煞N初始化方式方式一全局 Handler推薦利用llama_index.core提供的set_global_handler將 AgentOps 注冊(cè)為全局回調(diào)處理器from llama_index.core import set_global_handler set_global_handler(agentops, api_key...)在核心庫 global_handlers.py 中agentops分支會(huì)執(zhí)行懶加載——只有在調(diào)用時(shí)才從llama_index.callbacks.agentops導(dǎo)入AgentOpsHandler并執(zhí)行AgentOpsHandler.init(**eval_params)若包未安裝則拋出 ImportError 并提示安裝命令。這意味著api_key之外的所有關(guān)鍵字參數(shù)都可以通過set_global_handler原樣透?jìng)?。方式二直接初始?Handler如果你希望更顯式地控制處理器生命周期可以直接導(dǎo)入并初始化from llama_index.callbacks.agentops import AgentOpsHandler AgentOpsHandler.init(api_key...)該類的導(dǎo)出聲明位于init.py同時(shí)它也被注冊(cè)進(jìn) LlamaIndex 命令行映射見 mappings.json便于相關(guān)工具鏈識(shí)別。兩種方式底層走的是同一條路徑AgentOpsHandler.init()。init() 參數(shù)詳解根據(jù) base.py 中AgentOpsHandler.init()的方法簽名可用的關(guān)鍵字參數(shù)如下參數(shù)類型默認(rèn)值說明api_keyOptional[str]NoneAgentOps 平臺(tái) API Key用于身份認(rèn)證parent_keyOptional[str]None父級(jí) API KeyAgentOps 組織/賬戶層級(jí)擴(kuò)展場(chǎng)景endpointOptional[str]None自定義上報(bào)端點(diǎn)用于自托管 AgentOps 或代理環(huán)境max_wait_timeOptional[int]None事件批量上報(bào)的最大等待時(shí)間秒級(jí)max_queue_sizeOptional[int]None上報(bào)隊(duì)列的最大長(zhǎng)度超出后的處理策略由 AgentOps SDK 決定tagsOptional[List[str]]None附加到會(huì)話的標(biāo)簽列表便于在儀表盤按標(biāo)簽過濾instrument_llm_callsboolTrue是否由 AgentOps SDK 額外插樁 LLM 調(diào)用inherited_session_idOptional[str]None繼承已有會(huì)話 ID用于多進(jìn)程/多服務(wù)串聯(lián)同一會(huì)話init()內(nèi)部會(huì)將這些參數(shù)構(gòu)造為一個(gè)參數(shù)字典并過濾掉所有值為None的鍵后再傳給 AgentOps 的AOClient因此任何 AgentOpsAOClient支持的參數(shù)都可以沿用同名關(guān)鍵字透?jìng)鱎EADME 亦明確說明這一點(diǎn)。此外init()還強(qiáng)制注入了兩個(gè)會(huì)話行為參數(shù)auto_start_sessionTrue初始化后自動(dòng)開啟會(huì)話skip_auto_end_sessionFalse不跳過會(huì)話自動(dòng)結(jié)束邏輯即允許會(huì)話自動(dòng)結(jié)束。也就是說只要調(diào)用了init()AgentOps 會(huì)話生命周期管理會(huì)自動(dòng)開啟無需額外手動(dòng)調(diào)用。底層原理Span 與 Event 雙處理器架構(gòu)AgentOpsHandler繼承自核心庫的BaseInstrumentationHandler位于llama_index.core.instrumentation它本身不直接消費(fèi)事件而是在init()時(shí)從根 dispatcher 獲取分發(fā)器instrument.get_dispatcher()創(chuàng)建一對(duì)共享狀態(tài)的處理器并注冊(cè)AgentOpsSpanHandler繼承SimpleSpanHandler負(fù)責(zé) span 生命周期與異常關(guān)聯(lián)AgentOpsEventHandler繼承BaseEventHandler負(fù)責(zé)把 LlamaIndex 事件翻譯成 AgentOps 事件并調(diào)用ao_client.record()上報(bào)。兩者通過AgentOpsHandlerState一個(gè) Pydantic 模型共享運(yùn)行時(shí)狀態(tài)該狀態(tài)維護(hù)了四類映射span 是否源自 Agent 聊天is_agent_chat_span、Agent 聊天起始事件agent_chat_start_event、span 的父 spanspan_parent、span 內(nèi)拋出的異常集合span_exception。Span 處理器異常捕獲與上報(bào)AgentOpsSpanHandler在new_span時(shí)登記子 span 與父 span 的關(guān)聯(lián)在prepare_to_exit_span時(shí)清理狀態(tài)在prepare_to_drop_span時(shí)處理異常若當(dāng)前 span 因異常被丟棄先嘗試把異常關(guān)聯(lián)到父 span避免父 span 重復(fù)上報(bào)子 span 已記錄的異常若該異常尚未被記錄則調(diào)用self._ao_client.record(ErrorEvent(detailsstr(err)))上報(bào)為 AgentOps 的ErrorEvent。事件處理器LLM 與工具調(diào)用映射AgentOpsEventHandler.handle()只處理 Agent 場(chǎng)景下的事件核心映射邏輯如下AgentRunStepStartEvent標(biāo)記當(dāng)前 span 為 Agent 聊天 span觸發(fā)后續(xù)事件采集LLMChatStartEvent且處于 Agent 聊天 span 中緩存該事件的 span 關(guān)聯(lián)供結(jié)束事件回溯模型名LLMChatEndEvent且處于 Agent 聊天 span 中把消息列表轉(zhuǎn)換為{content, role}結(jié)構(gòu)作為prompt把響應(yīng)內(nèi)容作為completion并從response.raw[usage]中提取prompt_tokens/completion_tokens再通過get_chat_start_event()沿祖先 span 鏈回溯到對(duì)應(yīng)的 start 事件獲取model字段最終構(gòu)造LLMEvent上報(bào)AgentToolCallEvent將event.argumentsJSON 字符串反序列化為參數(shù)對(duì)象連同工具名構(gòu)造ToolEvent上報(bào)。其中check_is_agent_chat_span()會(huì)沿span_parent鏈遞歸檢查所有祖先 span判斷某個(gè)事件是否處于 Agent 運(yùn)行步驟之下get_chat_start_event()同樣沿祖先鏈尋找最近的LLMChatStartEvent。這正是只采集 Agent 場(chǎng)景下 LLM 調(diào)用這一設(shè)計(jì)意圖的實(shí)現(xiàn)細(xì)節(jié)。使用建議與注意事項(xiàng)Agent 場(chǎng)景限定從源碼可見普通非 Agent的 LLM 調(diào)用不會(huì)被采集——LLMChatEndEvent只有在is_agent_chat_event為真時(shí)才上報(bào)。若你的業(yè)務(wù)是純 RAG 問答而非 Agent 編排該集成可能無法覆蓋所有調(diào)用。異常自動(dòng)采集span 內(nèi)拋出的異常會(huì)自動(dòng)轉(zhuǎn)為ErrorEvent上報(bào)無需手動(dòng) try/except 包裝。版本配套包依賴llama-index-core0.13.0,0.15升級(jí) LlamaIndex 核心庫時(shí)請(qǐng)注意保持在該區(qū)間以免 instrumentation API 不兼容。自托管端點(diǎn)企業(yè)內(nèi)部部署 AgentOps 時(shí)通過endpoint參數(shù)指定上報(bào)地址即可。相關(guān)文件索引集成包 README官方安裝與初始化說明核心實(shí)現(xiàn) base.pyAgentOpsHandler、Span/Event 雙處理器與狀態(tài)模型包導(dǎo)出init.py公開 API 面包配置 pyproject.toml依賴與版本約束全局 Handler 注冊(cè)表set_global_handler(agentops, ...)的分發(fā)邏輯【免費(fèi)下載鏈接】llama_indexLlamaIndex is the document processing platform for AI項(xiàng)目地址: https://gitcode.com/GitHub_Trending/ll/llama_index創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考