年初接一個新項目的時候我一開始給的是那種“包一層API調(diào)一調(diào)”的demo演示效果很驚艷結果老板來一句“這個邏輯能不能換個模型試試”“這個流程能不能剪一段”我就傻了改prompt還好說想換模型、想改判斷分支代碼得扒半天測試又不全根本不敢動。那時候我就在想AI項目做到一定復雜度卡脖子的根本不是模型效果而是代碼能不能被自己穩(wěn)穩(wěn)控制住。后來我把整套思路重新捋了一遍就是圍繞著**“靈活、代碼可控”的BuildingAI理念**去重構——不把AI當成一個黑盒API塞進業(yè)務里而是把模型、流程、參數(shù)、輸出全拆開全部放在代碼能掌控的層面。這套東西做完之后再有人跟我說“換一下模型試試”我不會慌改一個配置項就能跑。今天我就把這套做法里最核心的骨架、設計取舍和一些實測中踩到的坑一起寫下來。1. 為什么AI構建必須回到“代碼可控”這條路上來先說一個我自己的感受過去AI項目的交付模式基本是“平臺化工具在線配置”。平臺把模型能力封裝得很好看你點點鼠標就能搭一個問答機器人?？烧嬲暇€跑起來之后問題的復雜度會迅速超過平臺能覆蓋的邊界。1.1 低代碼平臺和黑盒API的真實處境低代碼平臺的最大痛點是模板化。它給你很多現(xiàn)成的控件、節(jié)點、prompt槽位但這些控件之間的數(shù)據(jù)流是平臺定義好的。我想在兩個節(jié)點中間插一步“先判斷用戶意圖再決定要不要走檢索”平臺支持當然好不支持就得繞路哪怕支持節(jié)點多了之后連線密密麻麻出了問題根本不知道是哪條鏈路帶偏的。黑盒API的問題則在于不可觀察。API內(nèi)部做了什么、用了什么prompt模板、檢索結果怎么排序、模型在哪個版本上表現(xiàn)穩(wěn)定你都看不到。而生產(chǎn)環(huán)境恰恰需要的是“出問題時我能定位”。有一次線上機器人突然開始胡言亂語排查半天發(fā)現(xiàn)是上游模型悄悄升級了版本輸出風格全變了。這種“不可控制”會讓整個項目變得很被動。1.2 “靈活”在AI項目里到底指什么我后來定義的“靈活”不是能隨便問問題這種產(chǎn)品層面的靈活而是工程層面上的可調(diào)整性。具體拆開看大概是四件事模型可替換同一套業(yè)務代碼今天用這個模型明天能換另一個模型甚至換成私有化部署的模型中間不用大改。流程可編排意圖識別、知識檢索、上下文壓縮、答案生成這些步驟可以隨時增刪、調(diào)整順序像搭積木一樣可控。輸出可校驗模型返回的內(nèi)容在進到業(yè)務系統(tǒng)之前能被攔截、檢查格式、強制糾錯。策略可定制每個客戶、每個場景的prompt和參數(shù)都獨立配置互不干擾。這四條做到位外部環(huán)境再怎么變代碼主體都能穩(wěn)住。1.3 代碼可控的三個層次我自己習慣把“代碼可控”拆成三層來理解第一層是調(diào)用層也就是直接使用模型SDK。第二層是編排層負責把多個AI環(huán)節(jié)組織成一個完整流程。第三層是配置層把prompt、模型名、溫度參數(shù)、開關項這些易變的東西提取出來交給外部配置來控制。三層之間各司其職調(diào)用層管“怎么連”編排層管“怎么串”配置層管“怎么調(diào)”。這樣的分層思路是整個BuildingAI實踐的基石后面所有設計都是在這個框架里展開的。2. 搭建BuildingAI的最小骨架從模型網(wǎng)關到流程編排有了分層思路之后動手第一個要做的不是接模型而是先把地基打穩(wěn)。我建議第一步就是寫一個統(tǒng)一模型網(wǎng)關讓上層代碼不直接依賴任何一個具體模型供應商。2.1 模型網(wǎng)關讓模型可替換的第一步模型網(wǎng)關的作用相當于給所有模型提供同一個“插座”接口。上層業(yè)務只跟這個接口打交道底層換什么模型都不影響。from abc import ABC, abstractmethod from typing import List, Dict, Optional class ChatMessage: def __init__(self, role: str, content: str): self.role role self.content content class ModelGateway(ABC): abstractmethod def chat( self, messages: List[ChatMessage], temperature: Optional[float] None, max_tokens: Optional[int] None, model: Optional[str] None, ) - str: 統(tǒng)一的對話補全接口 pass以Python為例我定義了一個抽象基類任何模型供應商只要實現(xiàn)這個接口就能接入。接口上設計幾個關鍵點messages統(tǒng)一使用ChatMessage對象不直接暴露各廠商的原始結構。temperature和max_tokens是可選的不傳就用配置里的默認值。model參數(shù)允許在特殊場景下臨時指定模型。接著做一個具體實現(xiàn)比如OpenAI的接入import os from openai import OpenAI class OpenAIGateway(ModelGateway): def __init__(self, api_keyNone, base_urlNone): self.client OpenAI( api_keyapi_key or os.getenv(OPENAI_API_KEY), base_urlbase_url or os.getenv(OPENAI_BASE_URL), ) self.default_model os.getenv(OPENAI_MODEL, gpt-4o-mini) def chat(self, messages, temperatureNone, max_tokensNone, modelNone): resp self.client.chat.completions.create( modelmodel or self.default_model, messages[{role: m.role, content: m.content} for m in messages], temperaturetemperature, max_tokensmax_tokens, ) return resp.choices[0].message.content為什么網(wǎng)關層這么重要因為實際項目里“換模型”不是一次性動作而是常態(tài)。同一個客戶可能今天用A模型跑得挺好明天因為成本原因想換B模型或者同一個應用簡單問題走便宜模型復雜問題才走強模型。網(wǎng)關把這類切換從“改業(yè)務代碼”變成了“加一個實現(xiàn)類”。我后面甚至做了一個簡單的路由策略實現(xiàn)同一個網(wǎng)關里按問題類型自動選模型業(yè)務層無感。2.2 流程編排把AI能力拆成能被代碼控制的小步驟有了網(wǎng)關接下來是編排層。我借鑒了微服務里“編排”的概念把每一次AI交互從“一次大調(diào)用”拆成“多個可控小步驟”。舉個例子一個企業(yè)知識庫問答機器人它的處理鏈路我拆成了這樣意圖路由先判斷用戶是想問知識庫還是閑聊還是觸發(fā)某個工具。檢索觸發(fā)如果走知識庫則把問題向量化在向量數(shù)據(jù)庫里檢索相似段落。上下文組裝把檢索到的段落和對話歷史拼裝成一個精煉的上下文。生成回答調(diào)用模型生成最終答案。輸出校驗檢查答案是否包含知識庫里的關鍵信息點不含就拒絕并重新生成一次。每一步都可以被單獨測試、單獨替換。我寫編排的時候沒有引入重型框架而是定義了一個輕量的Step接口每個步驟只做一件事數(shù)據(jù)以字典上下文傳遞。class PipelineStep: def execute(self, ctx: dict) - dict: raise NotImplementedError class Pipeline: def __init__(self, steps: List[PipelineStep]): self.steps steps def run(self, ctx: dict) - dict: for step in self.steps: ctx step.execute(ctx) if ctx.get(abort): break return ctx這樣的代碼結構看起來平淡但對我來說它解決了最大的問題每個環(huán)節(jié)都能單獨改。比如檢索效果不好我只需要替換檢索步驟生成步驟根本不用動想加一個敏感詞檢測步驟往列表里插一段就行。2.3 配置與代碼分離不改代碼也能調(diào)整行為編排層穩(wěn)定之后最大的麻煩變成“每改一個prompt都要動代碼重新部署”。后來我把所有易變項全部提取到了YAML配置里線上調(diào)參只需改配置并熱加載不用碰代碼。# config/models.yaml chat_model: provider: openai model_name: gpt-4o-mini temperature: 0.3 max_tokens: 800 # config/prompts.yaml intent_route: system: | 你是意圖識別引擎只輸出一個詞knowledge / chitchat / tool。 ... qa_generate: system: | 你是企業(yè)知識庫助手只能根據(jù)提供的資料回答 資料不存在時明確說“未找到相關信息”。配置里還習慣放一些開關features: use_vector_search: true use_output_guard: true fallback_to_strong_model: false這些開關讓我在灰度發(fā)布和降級處理時有了極大的操作空間。有一次線上檢索服務抖動我直接把use_vector_search改成false機器人立刻降級成純模型問答模式保障了基本可用性然后才慢慢排查檢索集群的問題。3. 在可觀測性與調(diào)試能力上做設計而不是等問題出現(xiàn)再補救代碼可控的第二層理解是“可以看到、可以重放、可以定位”。很多AI項目給人的印象是“玄學”其實很大程度上是缺少可觀測性。我自己吃過虧所以后來把可觀測性做進了框架層而不是事后補日志。3.1 結構化日志與追蹤讓每次請求都有完整軌跡我給每次請求分配一個trace_id這個ID從入口傳遍所有步驟。每個步驟執(zhí)行時都會往結構化日志里寫模型名、prompt長度、輸出內(nèi)容、耗時、token用量。后面排查問題時直接按trace_id撈整條鏈路的日志一眼就能看出問題出在哪一步。import logging import time import uuid class LoggedStep(PipelineStep): def __init__(self, inner_step: PipelineStep): self.inner inner_step self.logger logging.getLogger(buildingai) def execute(self, ctx: dict) - dict: start time.time() trace_id ctx.setdefault(trace_id, uuid.uuid4().hex[:12]) try: result self.inner.execute(ctx) self.logger.info( step_ok, extra{ trace_id: trace_id, step: type(self.inner).__name__, cost_ms: round((time.time() - start) * 1000, 2), }, ) return result except Exception as e: self.logger.error( step_failed, extra{ trace_id: trace_id, step: type(self.inner).__name__, error: str(e), }, ) raise這個裝飾式的LoggedStep可以包在任何步驟外層日志也好、追蹤也好都不需要侵入業(yè)務代碼。3.2 輸出校驗與防御性兜底模型輸出是不可控的所以我在生成答案之后加了一道硬校驗。具體做法是根據(jù)場景定義一些檢查規(guī)則規(guī)則可以很簡單比如答案是否以預期格式開頭答案是否包含涉敏詞JSON字段是否能反序列化成功并且關鍵字段存在校驗失敗時不直接返回錯誤而是進入重新生成通道提示模型剛才的格式有問題讓它重試一次重試仍失敗就降級為兜底回答。class OutputGuardStep(PipelineStep): def __init__(self, max_retries1): self.max_retries max_retries def execute(self, ctx: dict) - dict: raw_answer ctx[raw_answer] for i in range(self.max_retries 1): problem self._validate(raw_answer) if not problem: ctx[answer] raw_answer return ctx # 把問題反饋給模型讓它自己修正 ctx[retry_feedback] problem raw_answer ctx[regenerate_answer](feedbackproblem) ctx[answer] self._fallback_answer() return ctx這類“校驗重試兜底”的鏈路才是生產(chǎn)環(huán)境里真正讓人放心的設計而不是把希望寄托在模型的“自覺”上。3.3 搭建回歸評估集讓改動有據(jù)可依代碼可控也意味著要能回答“這次改動到底有沒有變差”。我建了一個輕量的評估集就是幾十條有代表性的測試用例每次改同prompt或調(diào)配置之后批量跑一遍對比輸出質(zhì)量。用一個腳本統(tǒng)一跑把每條的輸入、輸出存下來手動或半自動對比新舊版本差異。這個機制不復雜但價值極高它給了我“改起來不怕”的底氣因為任何改動都能在幾分鐘內(nèi)看到整體影響而不是靠感覺。4. 一個實際場景讓對話機器人具備“換腦”能力前面講了這么多理念用個真實案例串起來會更清楚。我去年做了一個多租戶的客服機器人需求是不同客戶有不同的模型偏好、不同的知識庫、不同的語氣要求而且客戶可能隨時想調(diào)整。4.1 需求拆解與代碼組織這個項目的核心約束是模型不確定、流程不確定、prompt不確定。按照目前的BuildingAI思路我做了三件事實現(xiàn)OpenAI和Claude兩個網(wǎng)關類同時允許按租戶配置私有化模型接入。流程編排固定為“路由→檢索→組裝→生成→校驗”但每個步驟都從租戶配置里讀取參數(shù)。每個租戶一套獨立的prompt模板和模型參數(shù)。調(diào)用鏈路上入口根據(jù)租戶ID加載配置整個后續(xù)邏輯全部驅(qū)動于配置tenant_config load_tenant_config(tenant_id) gateway ModelGatewayFactory.create(tenant_config[provider]) pipeline build_pipeline(tenant_config) result pipeline.run({question: user_input, tenant_config: tenant_config})這樣客戶今天說“把模型換成Claude”我只改數(shù)據(jù)庫里provider字段明天說“回答要更簡短”我只調(diào)temperature和系統(tǒng)prompt模板甚至不需要發(fā)版。4.2 實測中遇到的三個真實問題方案跑起來后問題主要集中在幾個預料之外的地方。第一個問題是兩家模型的輸出格式風格差很多同樣的JSON要求OpenAI規(guī)規(guī)矩矩按樣例輸出Claude有時候會自作主張多包一層markdown代碼塊直接把解析器搞得崩潰。后來我在輸出校驗步驟里做了格式清洗并在prompt里加了強約束示例才算穩(wěn)住。這個事告訴我模型可替換不只是“接口可替換”行為歸一化才是真正難點。第二個問題是重試風暴。最開始超時重試沒有做退避控制高峰時一個慢請求會觸發(fā)多次重試反而把模型調(diào)用線程打滿。后來給網(wǎng)關里統(tǒng)一加了指數(shù)退避和最大重試次數(shù)限制快速失敗比原地等待更合理。第三個問題是token成本失控。上下文太長時成本漲得很快尤其多個步驟都拿全量歷史去拼其實很多歷史對當前問題沒用。我加了一個上下文壓縮步驟把歷史消息里和當前問題無關的部分過濾掉成本直接降了百分之四五十響應也快了很多。4.3 成本與延遲的可控性提到成本和延遲這也是“可控”的一部分。項目里每次調(diào)用都統(tǒng)計token數(shù)和耗時實時同步到一個簡單面板里。運營同學能看到每個客戶每天的消耗趨勢有人半夜跑腳本狂調(diào)用很快就能發(fā)現(xiàn)異常。代碼層面對成本的控制主要是通過模型分級簡單問題走便宜模型復雜問題才走貴模型。這個分級策略寫在配置里運營可以直接調(diào)整閾值不需要開發(fā)介入。5. 代碼可控的邊界哪些環(huán)節(jié)不必自己從頭造最后想潑一點冷水代碼可控不代表一切都要自己寫。實際工程里有些東西直接交給成熟工具和組件比自己造輪子穩(wěn)得多。5.1 過度開發(fā)的信號我自己經(jīng)歷過一個反面案例明明只是做一個內(nèi)部用的問答工具卻花了兩周時間去設計插件體系、多租戶隔離、可插拔流程。后來復盤發(fā)現(xiàn)核心交互就是“問一句話取一段資料生成一段答案”完全不需要那么重的抽象。所以我想提醒一點分層和可配置性是手段不是目的。如果項目只有一條流程、一個模型、不打算變那最樸素的寫法反而最穩(wěn)。什么情況下需要代碼可控這套思路我總結下來至少要滿足下面之一有多個模型接入需求且可能頻繁切換。有多套業(yè)務場景prompt和流程差異較大。需要自動化測試和批量回歸驗證。需要精細化管理成本和延遲靈活做降級。如果一條都不滿足簡單封裝就夠了。5.2 適合交給成熟工具的環(huán)節(jié)檢索這一環(huán)我建議直接用向量數(shù)據(jù)庫和現(xiàn)成embedding服務自己從頭實現(xiàn)語義檢索性價比很低。數(shù)據(jù)導入、切分、索引管理這些臟活累活成熟工具能幫你省一大半時間。流程編排也不需要引入重型的擬人化編排框架一個簡單的步驟列表就夠等流程復雜到代碼寫起來明顯別扭時再考慮引入可視化編排平臺。5.3 代碼可控與團隊協(xié)作的平衡還有一個點很容易被忽視代碼可控提高了系統(tǒng)的靈活性但也要求團隊里有人能讀懂整個鏈路。低代碼平臺讓業(yè)務人員也能拖出demo回到代碼之后這個門檻轉(zhuǎn)移到了工程團隊身上。所以我通常在項目里保留一份非常樸素的架構說明把“這個流程有幾個步驟、每步改哪里、配置項都有什么作用”寫得明明白白。這樣新成員接手時不至于對著代碼發(fā)懵。總的來說BuildingAI這條路走下來我最深的感受是AI應用變得可預測、可維護、可演進靠的不是某一個強大模型而是一整套代碼層面的掌控力。模型會變、需求會變但只要網(wǎng)關、編排、配置、可觀測這幾根柱子立住了變化來的時候就不會慌。最后分享一個小習慣每次發(fā)布新配置或新prompt之后我都會把線上真實請求和對應的完整上下文存一份脫敏樣本隔一段時間翻出來對比很多效果退化都是靠這種“存檔重放”的方式提前暴露的。