1. 從“智能體”到“系統(tǒng)”為什么我們需要新的架構(gòu)描述語(yǔ)言最近在幾個(gè)涉及智能體Agentic AI系統(tǒng)的項(xiàng)目里我反復(fù)被同一個(gè)問(wèn)題困擾怎么把這一團(tuán)“會(huì)思考的代碼”給團(tuán)隊(duì)里的產(chǎn)品、測(cè)試甚至新來(lái)的研發(fā)同學(xué)講清楚畫個(gè)流程圖太單薄只能描述單一流程體現(xiàn)不出智能體之間的協(xié)作和決策循環(huán)。寫份幾十頁(yè)的文檔沒(méi)人看而且AI系統(tǒng)的動(dòng)態(tài)性和不確定性讓靜態(tài)文檔寫完就過(guò)時(shí)。我們?cè)囘^(guò)用傳統(tǒng)的UML但那些類圖、序列圖在面對(duì)“感知-規(guī)劃-執(zhí)行-學(xué)習(xí)”這種持續(xù)演進(jìn)的智能體行為時(shí)顯得力不從心像是在用樂(lè)高說(shuō)明書去描述一個(gè)活生生的生態(tài)系統(tǒng)。這讓我想起了軟件工程里那句老話“架構(gòu)是那些重要的東西無(wú)論它們是什么。”對(duì)于智能體系統(tǒng)什么才是“重要的東西”是單個(gè)智能體的內(nèi)部算法嗎是數(shù)據(jù)流的走向嗎還是它們之間如何通過(guò)“對(duì)話”達(dá)成目標(biāo)我們需要一種方法既能勾勒出系統(tǒng)的宏觀輪廓又能深入到關(guān)鍵交互的細(xì)節(jié)并且能讓不同背景的干系人Stakeholder在同一套“語(yǔ)言”下達(dá)成共識(shí)。這時(shí)C4模型進(jìn)入了我們的視野。它不是銀彈但確實(shí)為我們提供了一套克制而實(shí)用的“建模詞匯表”。簡(jiǎn)單來(lái)說(shuō)C4模型是一種用于可視化軟件架構(gòu)的層次化方法。它通過(guò)四個(gè)不同抽象層級(jí)的“視圖”Context, Containers, Components, Code來(lái)描繪一個(gè)系統(tǒng)就像你用谷歌地圖可以先看全球視圖再放大到國(guó)家、城市最后看到某條街道。這種“分層描述”的思想恰好擊中了描述復(fù)雜智能體系統(tǒng)的痛點(diǎn)。在接下來(lái)的內(nèi)容里我會(huì)結(jié)合我們趟過(guò)的坑分享如何用C4的思維而不是生搬硬套其圖形來(lái)為你的智能體系統(tǒng)繪制一份大家都能看懂的“地圖”。2. C4模型精要四層視圖如何解構(gòu)復(fù)雜系統(tǒng)在直接套用到AI系統(tǒng)之前我們有必要先理解C4模型的本意。它由Simon Brown提出核心是通過(guò)不同的抽象層級(jí)來(lái)管理架構(gòu)描述的復(fù)雜性每一層都為特定類型的溝通而設(shè)計(jì)。很多人一上來(lái)就找工具畫圖卻忽略了每一層視圖要回答的核心問(wèn)題這是本末倒置。2.1 語(yǔ)境視圖Context Diagram系統(tǒng)與外部世界的邊界這是最高層次的視圖一張圖回答一個(gè)最根本的問(wèn)題“這個(gè)系統(tǒng)是什么它為誰(shuí)解決了什么問(wèn)題”內(nèi)容中心是你的待描述系統(tǒng)畫成一個(gè)方框。周圍是與之交互的“人”角色如用戶、管理員和“外部系統(tǒng)”如第三方API、數(shù)據(jù)庫(kù)、身份認(rèn)證服務(wù)。用連線表示他們之間的交互關(guān)系。價(jià)值它劃定了討論范圍讓所有人包括非技術(shù)高管對(duì)系統(tǒng)的存在價(jià)值和邊界達(dá)成一致。在我們一個(gè)智能客服項(xiàng)目中語(yǔ)境視圖清晰地顯示了“智能客服系統(tǒng)”與“終端用戶”、“人工坐席工作臺(tái)”、“知識(shí)庫(kù)系統(tǒng)”和“計(jì)費(fèi)系統(tǒng)”的關(guān)系避免了后續(xù)討論中不斷有人問(wèn)“這個(gè)功能算不算在我們系統(tǒng)里”。2.2 容器視圖Container Diagram技術(shù)選型與職責(zé)分配將系統(tǒng)放大一層容器視圖展示系統(tǒng)的“容器”以及它們之間如何通信。什么是容器一個(gè)容器是一個(gè)可獨(dú)立部署/運(yùn)行的應(yīng)用或數(shù)據(jù)存儲(chǔ)。例如一個(gè)Web應(yīng)用如Spring Boot服務(wù)、一個(gè)移動(dòng)App、一個(gè)單頁(yè)應(yīng)用SPA、一個(gè)數(shù)據(jù)庫(kù)MySQL、一個(gè)消息隊(duì)列Kafka、一個(gè)文件存儲(chǔ)S3。關(guān)鍵容器是技術(shù)選型的體現(xiàn)。內(nèi)容在語(yǔ)境視圖的系統(tǒng)框內(nèi)展開畫出所有的容器并顯示它們之間的通信協(xié)議如HTTP/HTTPS, gRPC, Kafka消息。價(jià)值它回答了“系統(tǒng)主要由哪些部分組成用了什么技術(shù)”這對(duì)于開發(fā)、運(yùn)維和基礎(chǔ)設(shè)施團(tuán)隊(duì)至關(guān)重要。對(duì)于智能體系統(tǒng)一個(gè)“推理服務(wù)容器”可能用PythonFastAPI和一個(gè)“向量數(shù)據(jù)庫(kù)容器”如Milvus就是典型的容器。2.3 組件視圖Component Diagram模塊化與內(nèi)部協(xié)作繼續(xù)放大聚焦于單個(gè)容器內(nèi)部。組件視圖描述一個(gè)容器內(nèi)部的主要邏輯組件及其關(guān)系。什么是組件組件是容器內(nèi)部的一個(gè)模塊化部分通常對(duì)應(yīng)代碼庫(kù)中的一個(gè)模塊、一個(gè)命名空間或一組強(qiáng)相關(guān)的類。例如在一個(gè)“智能體編排服務(wù)”容器內(nèi)可能有“任務(wù)解析組件”、“工具調(diào)用路由組件”、“多智能體會(huì)話管理組件”。內(nèi)容畫出該容器內(nèi)的關(guān)鍵組件以及它們之間如何通過(guò)方法調(diào)用、消息或事件進(jìn)行協(xié)作。價(jià)值它為開發(fā)人員提供了清晰的模塊邊界和職責(zé)劃分是進(jìn)行詳細(xì)設(shè)計(jì)和代碼結(jié)構(gòu)規(guī)劃的基礎(chǔ)。在智能體系統(tǒng)中這是描述“規(guī)劃器”、“執(zhí)行器”、“記憶模塊”等核心概念如何被實(shí)現(xiàn)為軟件組件的最佳層級(jí)。2.4 代碼視圖Code Diagram最終的實(shí)現(xiàn)細(xì)節(jié)這是最底層的視圖通常由IDE如UML類圖、實(shí)體關(guān)系圖根據(jù)源代碼自動(dòng)生成用于說(shuō)明具體的類、接口關(guān)系。在C4模型中這一層通常不建議手動(dòng)維護(hù)因?yàn)榇a即真相手動(dòng)繪圖極易過(guò)時(shí)。它的存在更多是理念上的完整性架構(gòu)描述可以一直向下追溯至代碼。核心原則每一層視圖都是下一層視圖的抽象隱藏不必要的細(xì)節(jié)。向業(yè)務(wù)方展示語(yǔ)境視圖向運(yùn)維展示容器視圖向開發(fā)團(tuán)隊(duì)展示組件視圖。這種分層溝通的能力是C4模型最大的魅力。3. 當(dāng)C4遇見智能體建模中的挑戰(zhàn)與適配將C4模型應(yīng)用于智能體系統(tǒng)Agentic AI Systems時(shí)我們不能機(jī)械地照搬。傳統(tǒng)的Web或微服務(wù)架構(gòu)組件間的交互是相對(duì)確定、請(qǐng)求-響應(yīng)式的。而智能體系統(tǒng)引入了自主性Autonomy、目標(biāo)導(dǎo)向Goal-Oriented和持續(xù)學(xué)習(xí)Learning等新維度這給建模帶來(lái)了獨(dú)特挑戰(zhàn)。3.1 挑戰(zhàn)一智能體作為“容器”還是“組件”這是第一個(gè)容易混淆的點(diǎn)。根據(jù)C4定義容器是可獨(dú)立部署的單元。那么一個(gè)擁有獨(dú)立進(jìn)程、通過(guò)API提供服務(wù)的“智能體服務(wù)”比如一個(gè)專用的“代碼生成智能體”它無(wú)疑是一個(gè)容器。然而在一個(gè)大型智能體應(yīng)用內(nèi)部可能存在多個(gè)輕量級(jí)的、作為庫(kù)Library集成在同一進(jìn)程內(nèi)的“技能智能體”例如一個(gè)“數(shù)據(jù)校驗(yàn)智能體”、一個(gè)“格式轉(zhuǎn)換智能體”。它們可能不被獨(dú)立部署但邏輯上高度自治。此時(shí)更合理的做法是將其視為容器內(nèi)部的一個(gè)頂級(jí)組件。關(guān)鍵在于是否具有獨(dú)立的運(yùn)行時(shí)邊界和通信成本。有則是容器無(wú)則是組件。實(shí)操心得不要糾結(jié)于絕對(duì)分類。我們的原則是如果某個(gè)智能體單元需要被其他系統(tǒng)甚至是其他容器內(nèi)的智能體以網(wǎng)絡(luò)API形式調(diào)用或者其擴(kuò)縮容策略獨(dú)立于主應(yīng)用那么就將其建模為容器。如果它只是主程序邏輯的一部分通過(guò)函數(shù)調(diào)用協(xié)作則建模為組件。這張圖是給活人看的實(shí)用清晰比理論正確更重要。3.2 挑戰(zhàn)二如何描述非確定性的交互流傳統(tǒng)軟件交互是“A調(diào)用BB返回結(jié)果”。智能體間的協(xié)作更像“對(duì)話”Dialogue或“行動(dòng)提議”Action Proposal。例如智能體A收到任務(wù)后可能會(huì)“咨詢”智能體BB返回一些信息或建議A再基于此決定下一步行動(dòng)。這種交互是雙向、多輪、可能基于上下文動(dòng)態(tài)變化的。在C4的容器/組件視圖上一條簡(jiǎn)單的連線不足以表達(dá)這種復(fù)雜交互。我們的做法是連線標(biāo)注在連接線上用標(biāo)簽簡(jiǎn)要說(shuō)明交互的性質(zhì)如“咨詢/建議”、“任務(wù)委派”、“結(jié)果同步”。配套說(shuō)明為復(fù)雜的協(xié)作模式創(chuàng)建單獨(dú)的序列圖Sequence Diagram作為補(bǔ)充文檔。C4模型并不排斥其他圖表它提供骨架細(xì)節(jié)用合適的工具補(bǔ)充。一張展示“多智能體協(xié)作完成復(fù)雜工單”的序列圖能極大地豐富架構(gòu)描述。引入“通道”或“黑板”容器對(duì)于基于消息或共享狀態(tài)的協(xié)作明確畫出消息隊(duì)列如RabbitMQ或共享內(nèi)存/數(shù)據(jù)庫(kù)作為“黑板”模式中的黑板作為一個(gè)獨(dú)立的容器。這能清晰表明智能體之間是通過(guò)中間媒介進(jìn)行解耦的通信。3.3 挑戰(zhàn)三工具使用Tool Use與外部服務(wù)的建模智能體的核心能力之一是調(diào)用工具Tools或外部API如搜索、計(jì)算、數(shù)據(jù)庫(kù)操作。在C4模型中這些工具和外部API應(yīng)被明確為外部系統(tǒng)在語(yǔ)境視圖或容器如果它們是系統(tǒng)內(nèi)自建的服務(wù)。例如一個(gè)智能體需要調(diào)用“天氣查詢API”。如果這是第三方服務(wù)那么在語(yǔ)境視圖中它就是系統(tǒng)邊界外的一個(gè)方框。如果這是系統(tǒng)內(nèi)部自建的一個(gè)“天氣數(shù)據(jù)聚合服務(wù)”那么它在容器視圖中就是一個(gè)獨(dú)立的容器。智能體與工具之間的調(diào)用關(guān)系用連線清晰標(biāo)示。這有助于在架構(gòu)層面厘清依賴評(píng)估第三方服務(wù)故障對(duì)系統(tǒng)的影響。3.4 挑戰(zhàn)四“記憶”Memory與“學(xué)習(xí)”Learning的體現(xiàn)智能體的長(zhǎng)期記憶如向量數(shù)據(jù)庫(kù)和持續(xù)學(xué)習(xí)如微調(diào)管道是架構(gòu)的關(guān)鍵部分。它們應(yīng)該被建模為容器。向量數(shù)據(jù)庫(kù)如Pinecone, Weaviate明確畫作一個(gè)“數(shù)據(jù)存儲(chǔ)”類型的容器。所有需要讀寫長(zhǎng)期記憶的智能體容器都指向它。模型微調(diào)管道這可能是一個(gè)獨(dú)立的批處理或工作流容器如用Airflow或Kubernetes CronJob實(shí)現(xiàn)的它從“反饋數(shù)據(jù)存儲(chǔ)”讀取數(shù)據(jù)訓(xùn)練模型并將新模型發(fā)布到“模型倉(cāng)庫(kù)”容器。智能體推理容器再?gòu)哪Ｐ蛡}(cāng)庫(kù)拉取最新模型。將這些元素顯式化使得資源規(guī)劃、數(shù)據(jù)流管理和版本控制策略一目了然。4. 實(shí)戰(zhàn)案例一個(gè)智能研發(fā)助手系統(tǒng)的C4架構(gòu)描述讓我們通過(guò)一個(gè)簡(jiǎn)化但真實(shí)的“智能研發(fā)助手系統(tǒng)”案例將上述理念具象化。該系統(tǒng)旨在幫助開發(fā)團(tuán)隊(duì)分析需求、生成和評(píng)審代碼、定位故障。4.1 第一步繪制語(yǔ)境視圖——?jiǎng)澏☉?zhàn)場(chǎng)我們首先繪制語(yǔ)境視圖確定系統(tǒng)邊界和主要外部交互方。核心系統(tǒng)“智能研發(fā)助手系統(tǒng)”。主要人物開發(fā)工程師提出需求、查看代碼建議、進(jìn)行交互式調(diào)試。技術(shù)負(fù)責(zé)人設(shè)定代碼規(guī)范、審查智能體生成的架構(gòu)建議。外部系統(tǒng)Git代碼倉(cāng)庫(kù)如GitLab系統(tǒng)從中讀取代碼歷史、提交信息。項(xiàng)目管理工具如Jira讀取用戶故事、任務(wù)描述。內(nèi)部制品倉(cāng)庫(kù)如Nexus獲取依賴庫(kù)信息。監(jiān)控告警平臺(tái)如Prometheus/Grafana讀取系統(tǒng)指標(biāo)和日志用于故障分析。這張圖向產(chǎn)品經(jīng)理和投資人清晰地傳達(dá)了系統(tǒng)的定位它是一個(gè)連接了開發(fā)生態(tài)中多種數(shù)據(jù)源和服務(wù)為開發(fā)人員提供智能支持的“大腦”。4.2 第二步繪制容器視圖——技術(shù)藍(lán)圖在語(yǔ)境視圖的“智能研發(fā)助手系統(tǒng)”框內(nèi)我們展開容器視圖。以下是核心容器AI網(wǎng)關(guān)容器一個(gè)Python FastAPI應(yīng)用。職責(zé)接收所有外部請(qǐng)求來(lái)自Web前端或API調(diào)用進(jìn)行認(rèn)證、限流、路由將請(qǐng)求分發(fā)到后端的智能體服務(wù)。它是系統(tǒng)的唯一入口。智能體編排服務(wù)容器一個(gè)核心的Python服務(wù)。職責(zé)理解復(fù)雜用戶意圖將任務(wù)分解為子任務(wù)協(xié)調(diào)不同的功能智能體協(xié)作完成。它維護(hù)會(huì)話狀態(tài)管理多輪對(duì)話。功能智能體容器群需求分析智能體服務(wù)專門解析自然語(yǔ)言需求生成用戶故事地圖或功能點(diǎn)列表。代碼生成/補(bǔ)全智能體服務(wù)根據(jù)上下文生成代碼片段或函數(shù)。代碼評(píng)審智能體服務(wù)分析代碼指出潛在bug、風(fēng)格問(wèn)題、性能隱患。故障診斷智能體服務(wù)結(jié)合日志、指標(biāo)和代碼變更推理故障根因。支撐服務(wù)容器向量數(shù)據(jù)庫(kù)容器存儲(chǔ)代碼片段、文檔、歷史經(jīng)驗(yàn)的嵌入向量供所有智能體進(jìn)行語(yǔ)義檢索。模型服務(wù)容器托管大語(yǔ)言模型LLM的推理API如通過(guò)vLLM或TGI部署。知識(shí)庫(kù)容器一個(gè)關(guān)系型數(shù)據(jù)庫(kù)如PostgreSQL存儲(chǔ)結(jié)構(gòu)化知識(shí)如團(tuán)隊(duì)規(guī)范、API文檔、系統(tǒng)架構(gòu)圖。消息隊(duì)列容器用于異步任務(wù)處理例如一個(gè)耗時(shí)的代碼庫(kù)全量分析任務(wù)可以被放入隊(duì)列由后臺(tái)工作者處理。Web前端容器一個(gè)React/Vue單頁(yè)應(yīng)用提供用戶交互界面。在圖中我們用箭頭標(biāo)明容器間的通信協(xié)議AI網(wǎng)關(guān)到編排服務(wù)是HTTP編排服務(wù)到各功能智能體可能是gRPC追求性能或HTTP智能體訪問(wèn)向量數(shù)據(jù)庫(kù)和模型服務(wù)通常是各自的客戶端協(xié)議。4.3 第三步深入關(guān)鍵容器——繪制組件視圖我們選擇最復(fù)雜的“智能體編排服務(wù)容器”和“代碼生成智能體服務(wù)容器”來(lái)繪制組件視圖。對(duì)于“智能體編排服務(wù)容器”其內(nèi)部可能包含以下組件會(huì)話管理組件維護(hù)用戶會(huì)話上下文包括歷史對(duì)話、當(dāng)前任務(wù)狀態(tài)。任務(wù)規(guī)劃與分解組件接收用戶目標(biāo)利用LLM或規(guī)則引擎將其分解為一系列可被功能智能體執(zhí)行的子任務(wù)序列。工具/智能體路由組件根據(jù)子任務(wù)類型決定調(diào)用哪個(gè)功能智能體或外部工具并組裝調(diào)用參數(shù)。結(jié)果聚合與評(píng)估組件收集各子任務(wù)執(zhí)行結(jié)果評(píng)估是否達(dá)成總目標(biāo)若未達(dá)成可能觸發(fā)新一輪規(guī)劃。對(duì)于“代碼生成智能體服務(wù)容器”其內(nèi)部可能包含上下文檢索組件從向量數(shù)據(jù)庫(kù)和知識(shí)庫(kù)中檢索與當(dāng)前任務(wù)最相關(guān)的代碼示例、API文檔。提示詞工程組件將用戶需求、檢索到的上下文、代碼規(guī)范等組合成結(jié)構(gòu)化的提示詞Prompt。LLM調(diào)用與緩存組件負(fù)責(zé)調(diào)用底層的模型服務(wù)容器并實(shí)現(xiàn)響應(yīng)緩存以優(yōu)化成本與延遲。后處理與驗(yàn)證組件對(duì)LLM生成的代碼進(jìn)行語(yǔ)法檢查、基礎(chǔ)安全掃描、格式化。通過(guò)這些組件視圖開發(fā)團(tuán)隊(duì)對(duì)每個(gè)服務(wù)的內(nèi)部模塊劃分和職責(zé)一目了然便于分工和代碼組織。4.4 第四步用動(dòng)態(tài)視圖補(bǔ)充關(guān)鍵場(chǎng)景靜態(tài)結(jié)構(gòu)圖不足以描述智能體的動(dòng)態(tài)行為。我們?yōu)椤疤幚硪粋€(gè)代碼生成請(qǐng)求”這個(gè)核心場(chǎng)景繪制了一張序列圖。用戶通過(guò)Web前端提交請(qǐng)求“為用戶登錄功能生成一個(gè)Spring Boot Controller。”前端調(diào)用AI網(wǎng)關(guān)。AI網(wǎng)關(guān)將請(qǐng)求轉(zhuǎn)發(fā)給智能體編排服務(wù)。編排服務(wù)的任務(wù)規(guī)劃組件分析請(qǐng)求識(shí)別出需要“代碼生成”能力。編排服務(wù)調(diào)用代碼生成智能體服務(wù)并附上會(huì)話上下文。代碼生成智能體的上下文檢索組件從向量數(shù)據(jù)庫(kù)中檢索類似的登錄Controller代碼。代碼生成智能體的提示詞工程組件組裝最終提示詞通過(guò)LLM調(diào)用組件請(qǐng)求模型服務(wù)。模型服務(wù)返回生成的代碼。代碼生成智能體的后處理組件進(jìn)行基礎(chǔ)檢查將結(jié)果返回給編排服務(wù)。編排服務(wù)可能將結(jié)果暫存或直接通過(guò)AI網(wǎng)關(guān)返回給前端展示給用戶。這張序列圖清晰地展示了數(shù)據(jù)流、組件協(xié)作順序和關(guān)鍵決策點(diǎn)是靜態(tài)架構(gòu)圖的最佳伴侶。5. 避坑指南智能體系統(tǒng)架構(gòu)文檔化的常見陷阱結(jié)合項(xiàng)目經(jīng)驗(yàn)在運(yùn)用C4或任何方法描述智能體系統(tǒng)架構(gòu)時(shí)有幾個(gè)陷阱需要特別注意。5.1 陷阱一過(guò)度建模陷入“繪圖泥潭”C4模型提倡“足夠多的架構(gòu)圖而不是過(guò)多的架構(gòu)圖”。智能體系統(tǒng)本身就在快速迭代初期不必追求面面俱到。我們的教訓(xùn)在一個(gè)項(xiàng)目初期我們?cè)噲D為每一個(gè)可能的智能體交互場(chǎng)景都畫序列圖導(dǎo)致文檔維護(hù)成本極高且很快與實(shí)際代碼脫節(jié)。改進(jìn)策略聚焦于核心流程和關(guān)鍵集成點(diǎn)。只維護(hù)那些對(duì)理解系統(tǒng)整體結(jié)構(gòu)、數(shù)據(jù)流和關(guān)鍵決策至關(guān)重要的視圖通常是語(yǔ)境視圖、容器視圖和2-3個(gè)核心場(chǎng)景的組件/序列圖。使用能根據(jù)代碼或配置自動(dòng)生成部分圖表的工具如Structurizr并將架構(gòu)文檔作為代碼Diagrams as Code來(lái)管理實(shí)現(xiàn)版本控制。5.2 陷阱二混淆邏輯架構(gòu)與部署架構(gòu)C4的容器視圖本質(zhì)上是邏輯部署視圖它顯示的是“有什么類型的可運(yùn)行東西”。但在云原生環(huán)境下一個(gè)“容器”C4概念可能對(duì)應(yīng)多個(gè)Kubernetes Pod部署概念。不要在C4圖中畫Pod、Node、Service這些K8s資源。清晰分層用C4容器視圖表達(dá)“有AI網(wǎng)關(guān)、編排服務(wù)、向量數(shù)據(jù)庫(kù)這些邏輯單元”。另外用一張部署圖可以使用簡(jiǎn)單的框圖或K8s生態(tài)的工具如Helm Charts描述來(lái)展示“AI網(wǎng)關(guān)由3個(gè)Pod副本組成前面有一個(gè)LoadBalancer Service”。兩者互補(bǔ)各司其職。5.3 陷阱三忽視非功能需求的體現(xiàn)架構(gòu)圖不能只展示“有什么”和“怎么連”還要暗示“好不好”。智能體系統(tǒng)尤其關(guān)注延遲、吞吐量、成本和安全。在圖中標(biāo)注關(guān)鍵指標(biāo)在容器間的連線上可以附加標(biāo)簽如“平均延遲200ms”、“數(shù)據(jù)流敏感用戶數(shù)據(jù)”、“調(diào)用頻率高頻”。在容器框內(nèi)可以簡(jiǎn)要注明“要求99.9%可用性”、“自動(dòng)擴(kuò)縮容”。配套文檔說(shuō)明為架構(gòu)圖編寫簡(jiǎn)短的說(shuō)明文字專門闡述針對(duì)高并發(fā)、低延遲、成本控制LLM API調(diào)用次數(shù)、數(shù)據(jù)隱私和安全智能體訪問(wèn)權(quán)限控制等方面的設(shè)計(jì)決策。例如解釋為什么將向量數(shù)據(jù)庫(kù)獨(dú)立部署以及它的緩存策略。5.4 陷阱四文檔與實(shí)現(xiàn)脫節(jié)淪為“僵尸文檔”這是所有架構(gòu)文檔的終極挑戰(zhàn)。智能體系統(tǒng)迭代更快文檔更容易過(guò)時(shí)。我們的實(shí)踐將架構(gòu)圖集成到CI/CD流程在代碼倉(cāng)庫(kù)中存儲(chǔ)圖表源文件如PlantUML文件。在README或特定文檔目錄中引用這些生成的圖片。每次代碼重大變更都需要更新對(duì)應(yīng)的圖表源文件這可以作為代碼審查的一部分。建立輕量級(jí)同步機(jī)制規(guī)定每次涉及容器新增/刪除、核心通信協(xié)議變更的合并請(qǐng)求Merge Request都必須更新對(duì)應(yīng)的C4容器視圖。將架構(gòu)視圖視為與API接口文檔同等重要的活文檔。使用可交互的架構(gòu)門戶如果條件允許使用像Backstage這樣的內(nèi)部開發(fā)者門戶將架構(gòu)圖、服務(wù)目錄、部署狀態(tài)、運(yùn)行手冊(cè)鏈接在一起讓架構(gòu)圖成為通往真實(shí)系統(tǒng)的一個(gè)動(dòng)態(tài)入口而不是一份靜態(tài)的PDF。描述智能體系統(tǒng)架構(gòu)目的不是為了產(chǎn)出漂亮的圖表而是為了在團(tuán)隊(duì)內(nèi)外建立共同的心智模型降低溝通成本并提前暴露設(shè)計(jì)風(fēng)險(xiǎn)。C4模型提供了一套極佳的分層框架來(lái)應(yīng)對(duì)復(fù)雜性。關(guān)鍵在于靈活運(yùn)用其思想結(jié)合智能體系統(tǒng)的特點(diǎn)進(jìn)行適配并始終牢記最好的架構(gòu)文檔是那些被團(tuán)隊(duì)持續(xù)使用和維護(hù)的文檔。它應(yīng)該像代碼一樣是系統(tǒng)的一個(gè)活生生的、有用的組成部分。