時(shí)搜索：Decagon對(duì)接Perplexity實(shí)戰(zhàn)指南)
在很多企業(yè)級(jí)智能客服項(xiàng)目中模型回答的“時(shí)效性”始終是一個(gè)繞不開(kāi)的話題?？蛻魰?huì)問(wèn)產(chǎn)品價(jià)格是否調(diào)整、系統(tǒng)當(dāng)前是否故障、附近網(wǎng)點(diǎn)是否還在營(yíng)業(yè)這類問(wèn)題需要依賴最新信息才能給出可靠答案。如果只依靠模型的靜態(tài)訓(xùn)練數(shù)據(jù)回答很容易過(guò)時(shí)甚至在大客戶面前留下不專業(yè)的印象。為了解決這個(gè)問(wèn)題業(yè)內(nèi)常用做法是在 AI 客服平臺(tái)里接入實(shí)時(shí)搜索服務(wù)把最新搜索結(jié)果作為回答依據(jù)。本文就圍繞 Decagon 接入 Perplexity 實(shí)時(shí)搜索服務(wù)這一大客戶集成場(chǎng)景梳理從需求分析、方案設(shè)計(jì)到代碼落地、生產(chǎn)排錯(cuò)的完整過(guò)程希望給正在做類似對(duì)接的團(tuán)隊(duì)提供一份可參考的工程筆記。1. 背景與核心概念1.1 為什么大客戶需要實(shí)時(shí)搜索能力大型企業(yè)客戶的客服場(chǎng)景通常對(duì)準(zhǔn)確率和時(shí)效性要求非常高。一個(gè)集團(tuán)客戶可能每天收到上千條咨詢其中不少問(wèn)題涉及當(dāng)天發(fā)生的變更比如價(jià)格策略、物流公告、產(chǎn)品版本發(fā)布、系統(tǒng)維護(hù)通知等。傳統(tǒng)做法是把資料預(yù)先導(dǎo)入知識(shí)庫(kù)再通過(guò)向量檢索找答案但這類方式有兩個(gè)明顯問(wèn)題第一知識(shí)庫(kù)更新依賴人工上傳響應(yīng)速度慢第二一些外部信息比如競(jìng)品動(dòng)態(tài)、行業(yè)政策、實(shí)時(shí)天氣根本無(wú)法提前入庫(kù)。實(shí)時(shí)搜索能力恰好能補(bǔ)上這個(gè)短板讓客服機(jī)器人在回答前主動(dòng)檢索最新網(wǎng)頁(yè)信息再結(jié)合模型的語(yǔ)言組織能力生成答案既保留了自然對(duì)話體驗(yàn)又讓回答有據(jù)可查。更重要的是大客戶在采購(gòu)企業(yè)級(jí)服務(wù)時(shí)會(huì)格外關(guān)注答案的“可信度”。他們不會(huì)接受一個(gè)只會(huì)說(shuō)“可能”“大概”的機(jī)器人而是希望看到回答附帶來(lái)源鏈接和更新時(shí)間。Perplexity 這類實(shí)時(shí)搜索服務(wù)恰好能提供帶引用來(lái)源的搜索結(jié)果Decagon 作為客戶支持自動(dòng)化平臺(tái)則負(fù)責(zé)把搜索能力編排到具體的客服會(huì)話流程中。兩者結(jié)合后客服機(jī)器人既能理解客戶意圖又能實(shí)時(shí)獲取外部世界的最新變化最終在保證體驗(yàn)的同時(shí)提升解決率。1.2 Decagon 在集成中扮演的角色Decagon 是一個(gè)面向企業(yè)級(jí)客戶的 AI 客服支持平臺(tái)它的核心價(jià)值在于把大語(yǔ)言模型、業(yè)務(wù)系統(tǒng)、客服工作流和自動(dòng)化工具編排在一起。簡(jiǎn)單理解Decagon 是“大腦和指揮中心”負(fù)責(zé)理解用戶消息、判斷意圖、調(diào)用工具、組織回復(fù)同時(shí)還要兼顧多輪對(duì)話、工單生成、人工接管等業(yè)務(wù)邏輯。在大客戶接入項(xiàng)目中Decagon 通常已經(jīng)具備穩(wěn)定的會(huì)話入口、用戶身份體系、工單系統(tǒng)和知識(shí)庫(kù)。接入實(shí)時(shí)搜索時(shí)我們不需要把所有搜索邏輯寫(xiě)死在業(yè)務(wù)代碼里而是把實(shí)時(shí)搜索封裝成一個(gè)“工具服務(wù)”由 Decagon 在需要時(shí)調(diào)用。這種解耦方式對(duì)項(xiàng)目落地非常關(guān)鍵。一方面實(shí)時(shí)搜索服務(wù)的接口和邏輯可以獨(dú)立升級(jí)不會(huì)影響 Decagon 本身的穩(wěn)定性另一方面大客戶往往有嚴(yán)格的安全審計(jì)要求把搜索服務(wù)獨(dú)立出來(lái)能更清晰地控制數(shù)據(jù)流向記錄每一次外部請(qǐng)求。所以在設(shè)計(jì)階段建議把 Decagon 與實(shí)時(shí)搜索服務(wù)放在兩個(gè)不同模塊中盡量通過(guò)標(biāo)準(zhǔn) REST 接口或消息隊(duì)列通信而不是直接把搜索邏輯嵌入到會(huì)話處理的主鏈路里。1.3 Perplexity 實(shí)時(shí)搜索服務(wù)的定位Perplexity 是當(dāng)前比較有代表性的 AI 實(shí)時(shí)搜索服務(wù)它擅長(zhǎng)的正是“搜索 生成”的組合根據(jù)用戶輸入的關(guān)鍵詞或問(wèn)題實(shí)時(shí)檢索互聯(lián)網(wǎng)內(nèi)容再把檢索結(jié)果整理成帶引用的回答。對(duì)企業(yè)級(jí)集成來(lái)說(shuō)Perplexity 的價(jià)值不僅是返回一段答案而是能把“信息來(lái)源”一起帶回來(lái)這正好滿足了大客戶對(duì)答案可追溯的訴求。在實(shí)際接入時(shí)我們需要把它看成一種“外部數(shù)據(jù)源”而不是一個(gè)黑盒聊天機(jī)器人。需要注意的是Perplexity 的接口參數(shù)、鑒權(quán)方式、限流策略可能在不斷更新本文不會(huì)把某個(gè)固定版本的細(xì)節(jié)作為唯一標(biāo)準(zhǔn)。技術(shù)團(tuán)隊(duì)拿到授權(quán)后應(yīng)以服務(wù)商提供的最新 API 文檔為準(zhǔn)。我們?cè)谶@篇文章中更多是分享一套通用的集成思路如何配置密鑰、如何封裝請(qǐng)求、如何解析返回、如何做緩存和降級(jí)。只要掌握這些套路即使接口細(xì)節(jié)變化也能快速適配。2. 大客戶接入方案整體設(shè)計(jì)2.1 接入流程概覽大客戶接入實(shí)時(shí)搜索服務(wù)不能一上來(lái)就寫(xiě)代碼。建議先梳理一條完整的數(shù)據(jù)鏈路確保每個(gè)環(huán)節(jié)的責(zé)任邊界清晰。整體流程可以拆成六個(gè)步驟第一步在服務(wù)商后臺(tái)申請(qǐng)實(shí)時(shí)搜索服務(wù)的訪問(wèn)憑證第二步在企業(yè)內(nèi)部網(wǎng)絡(luò)規(guī)劃中放通與搜索服務(wù)之間的訪問(wèn)通道第三步開(kāi)發(fā)一個(gè)標(biāo)準(zhǔn)化的搜索客戶端統(tǒng)一管理鑒權(quán)、請(qǐng)求、超時(shí)和重試第四步把搜索客戶端封裝成 Decagon 可調(diào)用的工具接口第五步在 Decagon 會(huì)話流程中配置觸發(fā)條件和提示詞模板第六步上線前完成權(quán)限、日志、審計(jì)和熔斷策略的驗(yàn)證。這個(gè)流程看起來(lái)簡(jiǎn)單但真正執(zhí)行時(shí)經(jīng)?？ㄔ诰W(wǎng)絡(luò)策略和賬號(hào)權(quán)限上。大客戶環(huán)境通常有嚴(yán)格的防火墻規(guī)則哪些部門可以調(diào)用外部 API哪些環(huán)境可以存儲(chǔ)密鑰都需要提前確認(rèn)。另外建議在測(cè)試環(huán)境先打通一條最小鏈路用固定問(wèn)題驗(yàn)證搜索返回、結(jié)果解析和 answer 組裝再逐步放開(kāi)到生產(chǎn)環(huán)境。2.2 網(wǎng)絡(luò)與安全設(shè)計(jì)實(shí)時(shí)搜索服務(wù)通常屬于外部 API企業(yè)內(nèi)部服務(wù)調(diào)用時(shí)需要經(jīng)過(guò)安全邊界。常見(jiàn)方式有兩種一種是直接通過(guò)公網(wǎng)訪問(wèn)使用 API Key 或 Token 鑒權(quán)另一種是在企業(yè)內(nèi)部部署代理網(wǎng)關(guān)由網(wǎng)關(guān)統(tǒng)一轉(zhuǎn)發(fā)外部請(qǐng)求方便在網(wǎng)關(guān)層做審計(jì)、限流和脫敏。對(duì)大客戶項(xiàng)目更推薦后者因?yàn)榇砭W(wǎng)關(guān)可以隱藏內(nèi)部服務(wù)結(jié)構(gòu)也方便統(tǒng)一控制訪問(wèn)范圍。安全設(shè)計(jì)上必須重點(diǎn)關(guān)注密鑰保管。不要把 API Key 直接寫(xiě)在代碼里更不要提交到 Git 倉(cāng)庫(kù)。推薦使用環(huán)境變量或配置中心管理密鑰并在服務(wù)啟動(dòng)時(shí)校驗(yàn)密鑰是否存在。如果是 Kubernetes 環(huán)境可以使用 Secret 對(duì)象保存如果是 Spring Cloud 體系可以使用配置中心加解密。網(wǎng)絡(luò)層面如果服務(wù)商支持 IP 白名單建議按生產(chǎn)環(huán)境出口 IP 配置白名單降低密鑰泄露后被濫用的風(fēng)險(xiǎn)。2.3 數(shù)據(jù)流與時(shí)序設(shè)計(jì)一次完整的實(shí)時(shí)搜索會(huì)話可以這樣描述客戶向 Decagon 發(fā)起咨詢Decagon 判斷當(dāng)前問(wèn)題需要外部最新信息Decagon 調(diào)用企業(yè)內(nèi)部搜索網(wǎng)關(guān)搜索網(wǎng)關(guān)向 Perplexity 服務(wù)發(fā)起實(shí)時(shí)搜索請(qǐng)求搜索服務(wù)返回答案和引用來(lái)源搜索網(wǎng)關(guān)把結(jié)果標(biāo)準(zhǔn)化后返回給 DecagonDecagon 結(jié)合業(yè)務(wù)上下文生成最終回復(fù)并把引用鏈接展示給客戶。整個(gè)過(guò)程中Decagon 只負(fù)責(zé)流程編排不直接感知 Perplexity 的內(nèi)部實(shí)現(xiàn)。為了便于排查問(wèn)題每次調(diào)用都要生成唯一的請(qǐng)求 ID并貫穿整個(gè)鏈路。建議至少記錄以下字段調(diào)用時(shí)間、請(qǐng)求 ID、客戶租戶 ID、查詢內(nèi)容、返回狀態(tài)、耗時(shí)、引用來(lái)源數(shù)量。大客戶審計(jì)時(shí)往往需要提供某一時(shí)間段內(nèi)的外部搜索調(diào)用明細(xì)如果我們沒(méi)有做日志事后補(bǔ)數(shù)據(jù)會(huì)非常痛苦。所以在方案設(shè)計(jì)階段就要把審計(jì)日志當(dāng)成核心功能而不是后期補(bǔ)丁。3. 環(huán)境準(zhǔn)備與前置條件3.1 賬號(hào)與權(quán)限準(zhǔn)備接入前需要確認(rèn)三個(gè)賬號(hào)維度實(shí)時(shí)搜索服務(wù)商賬號(hào)、Decagon 管理后臺(tái)賬號(hào)、企業(yè)內(nèi)部用于部署服務(wù)的云平臺(tái)或服務(wù)器賬號(hào)。實(shí)時(shí)搜索服務(wù)商賬號(hào)通常要申請(qǐng) API Key部分企業(yè)級(jí)套餐還會(huì)提供專屬 endpoint 和更高配額。Decagon 管理后臺(tái)需要具備工具配置和會(huì)話流編輯權(quán)限。企業(yè)內(nèi)部服務(wù)器賬號(hào)則需具備部署程序、讀取環(huán)境變量、寫(xiě)入日志的權(quán)限。這里要特別提醒大客戶項(xiàng)目建議使用獨(dú)立的服務(wù)賬號(hào)不要用個(gè)人賬號(hào)申請(qǐng)密鑰。這樣即使員工離職也可以通過(guò)回收服務(wù)賬號(hào)權(quán)限來(lái)保證系統(tǒng)安全。同時(shí)在服務(wù)商后臺(tái)最好配置多個(gè) Key 分別用于測(cè)試環(huán)境和生產(chǎn)環(huán)境避免測(cè)試流量影響生產(chǎn)配額也方便成本核算。3.2 開(kāi)發(fā)語(yǔ)言與依賴版本本文的示例代碼以 Python 和 Java 為主因?yàn)檫@兩種語(yǔ)言在企業(yè)服務(wù)端最常用。Python 示例使用 requests 作為 HTTP 客戶端依賴簡(jiǎn)潔容易理解Java 示例使用 Spring Boot 的 RestTemplate方便接入現(xiàn)有微服務(wù)體系。需要說(shuō)明的是requests 和 RestTemplate 只是工具不是唯一選擇你可以換成 httpx、OkHttp、WebClient 等核心思路不變。版本方面沒(méi)有強(qiáng)制要求建議使用較為穩(wěn)定的版本即可。如果你的項(xiàng)目是 Python 3.9直接安裝 requests 最新穩(wěn)定版如果是 Spring Boot 2.7RestTemplate 是內(nèi)置能力不需要額外依賴。關(guān)鍵是確認(rèn)你的應(yīng)用服務(wù)器能夠訪問(wèn)到實(shí)時(shí)搜索服務(wù)域名否則代碼寫(xiě)得再完善也會(huì)在連接階段超時(shí)。3.3 示例項(xiàng)目結(jié)構(gòu)為了演示方便我們規(guī)劃一個(gè)最小的項(xiàng)目結(jié)構(gòu)。后端服務(wù)提供兩個(gè)能力一個(gè)是標(biāo)準(zhǔn)的搜索 REST 接口供 Decagon 調(diào)用另一個(gè)是內(nèi)部工具函數(shù)用于測(cè)試和調(diào)試。search-service/ ├── src/ │ ├── main/ │ │ ├── java/com/example/search/ │ │ │ ├── SearchController.java │ │ │ ├── SearchClient.java │ │ │ ├── SearchRequest.java │ │ │ └── SearchResponse.java │ │ └── resources/application.yml │ └── test/ ├── python-demo/ │ ├── search_client.py │ ├── normalize_result.py │ └── .env.example └── README.mdPython 部分主要用來(lái)說(shuō)明客戶端封裝思路Java 部分用來(lái)展示如何把搜索接口暴露給 Decagon 去調(diào)用。實(shí)際項(xiàng)目中不需要完全照搬這個(gè)結(jié)構(gòu)但建議把“客戶端封裝”和“接口暴露”分層便于后期維護(hù)。4. 核心代碼實(shí)現(xiàn)封裝實(shí)時(shí)搜索客戶端4.1 配置管理無(wú)論使用哪種語(yǔ)言第一步都是把搜索服務(wù)的 endpoint 和 API Key 放到配置中。不要硬編碼。Python 項(xiàng)目可以使用.env文件配合os.getenv讀取Java 項(xiàng)目可以放在application.yml中并通過(guò)Value注入。下面是一個(gè).env.example示例實(shí)際使用時(shí)應(yīng)復(fù)制為.env并填入真實(shí)值# .env.example PERPLEXITY_API_URLhttps://your-search-endpoint.example.com/v1/query PERPLEXITY_API_KEYsk-xxxxxxxxxxxxxxxx SEARCH_TIMEOUT_MS30000 SEARCH_MAX_TOKENS600對(duì)應(yīng)的 Python 讀取代碼import os PERPLEXITY_API_URL os.getenv(PERPLEXITY_API_URL, ) PERPLEXITY_API_KEY os.getenv(PERPLEXITY_API_KEY, ) SEARCH_TIMEOUT int(os.getenv(SEARCH_TIMEOUT_MS, 30000)) / 1000 SEARCH_MAX_TOKENS int(os.getenv(SEARCH_MAX_TOKENS, 600))這里的默認(rèn)值只做演示企業(yè)環(huán)境應(yīng)通過(guò)環(huán)境變量強(qiáng)制注入不要在代碼中保留默認(rèn) Key。如果啟動(dòng)時(shí)發(fā)現(xiàn) Key 為空可以直接拋異常避免帶著錯(cuò)誤配置上線。4.2 請(qǐng)求封裝Python 示例實(shí)時(shí)搜索服務(wù)的 HTTP 調(diào)用通常遵循 REST 風(fēng)格方法為 POST請(qǐng)求體為 JSON。下面這段代碼演示了如何把查詢文本、最大返回長(zhǎng)度等參數(shù)發(fā)送到搜索服務(wù)。請(qǐng)注意示例中的 URL 是占位地址真實(shí)項(xiàng)目務(wù)必替換為服務(wù)方提供的 endpoint。import os import requests from typing import Dict, Optional PERPLEXITY_API_URL os.getenv(PERPLEXITY_API_URL, ) PERPLEXITY_API_KEY os.getenv(PERPLEXITY_API_KEY, ) def search_real_time(query: str, max_tokens: int 600) - Optional[Dict]: 調(diào)用 Perplexity 實(shí)時(shí)搜索接口。 :param query: 客戶問(wèn)題或搜索關(guān)鍵詞 :param max_tokens: 搜索生成結(jié)果的最大長(zhǎng)度 :return: 解析后的 JSON 字典失敗時(shí)返回 None if not PERPLEXITY_API_URL or not PERPLEXITY_API_KEY: raise RuntimeError(搜索服務(wù)地址或 API Key 未配置) headers { Authorization: fBearer {PERPLEXITY_API_KEY}, Content-Type: application/json, } payload { query: query, max_tokens: max_tokens, stream: False, } try: resp requests.post( PERPLEXITY_API_URL, headersheaders, jsonpayload, timeout30 ) resp.raise_for_status() return resp.json() except requests.exceptions.Timeout: print([search_real_time] 請(qǐng)求超時(shí)請(qǐng)稍后重試) except requests.exceptions.RequestException as e: print(f[search_real_time] 請(qǐng)求失敗: {e}) return None這段代碼有幾個(gè)關(guān)鍵點(diǎn)。第一使用Authorization: Bearer傳遞密鑰這是最常見(jiàn)的 HTTP API 鑒權(quán)方式如果你的服務(wù)商要求自定義頭字段只需要調(diào)整 headers 字典。第二設(shè)置了 30 秒超時(shí)避免下游異常導(dǎo)致整個(gè)業(yè)務(wù)線程長(zhǎng)時(shí)間阻塞。第三用raise_for_status()統(tǒng)一處理 4xx 和 5xx 錯(cuò)誤方便上層感知調(diào)用失敗。實(shí)際開(kāi)發(fā)中建議把超時(shí)時(shí)間放到配置里并區(qū)分“連接超時(shí)”和“讀取超時(shí)”。4.3 結(jié)果標(biāo)準(zhǔn)化Python 示例實(shí)時(shí)搜索服務(wù)返回的 JSON 結(jié)構(gòu)可能比較雜亂不同接口返回的字段名也可能不同。為了讓 Decagon 側(cè)不感知下游變化我們要在客戶端內(nèi)部做一次標(biāo)準(zhǔn)化轉(zhuǎn)換。假設(shè)搜索返回結(jié)果中包含答案文本、引用列表和請(qǐng)求消耗的 token 數(shù)我們可以統(tǒng)一成下面這種結(jié)構(gòu)。from typing import Dict, List, Any def normalize_search_result(raw: Dict[str, Any]) - Dict[str, Any]: 將搜索接口原始返回轉(zhuǎn)換為標(biāo)準(zhǔn)化結(jié)構(gòu)。 # 這里需要根據(jù)真實(shí)接口返回做字段映射下面是示例邏輯 answer raw.get(answer) or raw.get(text) or raw.get(result) or citations raw.get(citations) or raw.get(sources) or [] normalized { answer: answer, citations: [], query: raw.get(query, ), created_at: raw.get(created_at) or raw.get(timestamp, ), } for item in citations: if isinstance(item, str): normalized[citations].append({url: item, title: item}) elif isinstance(item, dict): normalized[citations].append({ url: item.get(url, ), title: item.get(title, item.get(url, )), }) return normalized標(biāo)準(zhǔn)化層最大的價(jià)值是屏蔽下游差異。例如服務(wù)商某天調(diào)整了返回字段從answer改成了text我們只需要修改標(biāo)準(zhǔn)化函數(shù)Decagon 的業(yè)務(wù)代碼完全不用動(dòng)。這種防御式編程思路在對(duì)接外部服務(wù)時(shí)非常重要尤其是大客戶項(xiàng)目版本升級(jí)頻繁接口小調(diào)整很難避免。4.4 Java 側(cè)接口暴露RestTemplate 示例如果企業(yè)技術(shù)棧是 Java通常會(huì)把搜索能力封裝成 Spring Boot 服務(wù)。下面展示一個(gè)最簡(jiǎn)單的 SearchClient它使用 RestTemplate 發(fā)送 POST 請(qǐng)求并通過(guò) DTO 接收返回。這里同樣是演示思路接口地址和 DTO 字段需要根據(jù)實(shí)際協(xié)議設(shè)計(jì)。// SearchClient.java import org.springframework.beans.factory.annotation.Value; import org.springframework.http.*; import org.springframework.stereotype.Component; import org.springframework.web.client.RestTemplate; import java.util.HashMap; import java.util.Map; Component public class SearchClient { private final RestTemplate restTemplate new RestTemplate(); Value(${perplexity.api-url}) private String apiUrl; Value(${perplexity.api-key}) private String apiKey; public SearchResponse search(String query) { HttpHeaders headers new HttpHeaders(); headers.setBearerAuth(apiKey); headers.setContentType(MediaType.APPLICATION_JSON); MapString, Object body new HashMap(); body.put(query, query); HttpEntityMapString, Object requestEntity new HttpEntity(body, headers); ResponseEntitySearchResponse response restTemplate.exchange( apiUrl, HttpMethod.POST, requestEntity, SearchResponse.class ); return response.getBody(); } }Java 版本的核心思路和 Python 一致都是“密鑰放配置 請(qǐng)求封裝 超時(shí)處理”。在實(shí)際項(xiàng)目中建議把 RestTemplate 換成帶連接池和超時(shí)配置的實(shí)例并接入公司的鏈路追蹤組件。SearchResponse 的字段可以根據(jù)接口返回定義如果你不想定義實(shí)體也可以用JsonNode接收再手動(dòng)標(biāo)準(zhǔn)化。5. 將搜索能力集成為 Decagon 工具5.1 工具調(diào)用Tool Calling思路Decagon 這類 AI 客服平臺(tái)通常會(huì)提供 tool calling 機(jī)制。也就是說(shuō)當(dāng)大模型判斷用戶問(wèn)題需要外部信息時(shí)會(huì)生成一個(gè)“調(diào)用實(shí)時(shí)搜索工具”的動(dòng)作平臺(tái)再根據(jù)這個(gè)動(dòng)作去請(qǐng)求搜索服務(wù)。因此我們不需要修改 Decagon 的底層模型只需要在控制臺(tái)或代碼中注冊(cè)一個(gè)搜索工具并明確工具的入?yún)⒑统鰠?。以常?jiàn)的配置方式為例我們的搜索工具可以聲明成工具名稱為real_time_search參數(shù)是querystring必填輸出是一段標(biāo)準(zhǔn)化的 JSON。Decagon 收到用戶問(wèn)題后會(huì)通過(guò)提示詞判斷是否觸發(fā)該工具。這種設(shè)計(jì)的好處是搜索能力可以被復(fù)用無(wú)論用戶問(wèn)的是售后政策、物流狀態(tài)還是競(jìng)品對(duì)比只要模型認(rèn)為需要最新外部信息都會(huì)自動(dòng)調(diào)用同一套搜索服務(wù)。5.2 提示詞模板設(shè)計(jì)提示詞是決定搜索效果的關(guān)鍵部分。如果提示詞寫(xiě)得太簡(jiǎn)單模型可能不知道該在什么時(shí)候搜索或者把搜索結(jié)果和自身知識(shí)混在一起。建議給 Decagon 配置類似下面這種提示詞模板。你是一位企業(yè)級(jí)客服助手。你的任務(wù)是根據(jù)用戶問(wèn)題給出準(zhǔn)確、禮貌、有依據(jù)的回答。 使用工具 real_time_search 的條件 1. 用戶詢問(wèn)的內(nèi)容可能隨時(shí)間變化例如價(jià)格、政策、庫(kù)存、公告、新聞。 2. 用戶要求提供最新信息例如“現(xiàn)在”“最新”“今天”等。 3. 你需要補(bǔ)充訓(xùn)練數(shù)據(jù)中沒(méi)有覆蓋的外部信息。 使用工具時(shí)請(qǐng)遵循以下要求 - 根據(jù)用戶問(wèn)題生成簡(jiǎn)潔的 query。 - 等待搜索結(jié)果返回后優(yōu)先使用搜索結(jié)果組織答案。 - 在答案中標(biāo)注引用來(lái)源使用引用編號(hào)或鏈接。 - 如果搜索結(jié)果為空或與問(wèn)題不相關(guān)需要明確告訴用戶暫時(shí)無(wú)法找到可靠信息。這段模板既指導(dǎo)了大模型何時(shí)調(diào)用工具也規(guī)范了答案輸出格式。大客戶對(duì)回復(fù)風(fēng)格通常有嚴(yán)格要求網(wǎng)上可以搜到引用來(lái)源但語(yǔ)言仍需保持克制和專業(yè)不能因?yàn)樗阉鹘Y(jié)果中包含營(yíng)銷詞匯就把客服回復(fù)變成廣告文案。5.3 流式輸出與引用展示大客戶場(chǎng)景中用戶體驗(yàn)要求較高回答最好能流式輸出讓客戶不用等待太久。但實(shí)時(shí)搜索本身有網(wǎng)絡(luò)耗時(shí)通常不會(huì)直接對(duì)整個(gè) answer 做流式處理而是先快速返回“正在搜索最新信息……”的提示再在后臺(tái)完成搜索后將搜索結(jié)果作為下一輪消息返回。這樣體驗(yàn)更順暢。引用展示也需要設(shè)計(jì)好。普通搜索工具返回的 citations 是 URL 列表但 Decagon 頁(yè)面展示時(shí)可能需要在答案末尾顯示來(lái)源鏈接?？蛻舳嗽跇?biāo)準(zhǔn)化結(jié)果時(shí)要保留 citations 的原始順序并為每一條生成短標(biāo)題。如果鏈接被截?cái)嘀辽俳o出域名方便客戶判斷來(lái)源可信度。6. 大客戶場(chǎng)景的進(jìn)階配置6.1 多租戶隔離與配額管理服務(wù)多個(gè)大客戶時(shí)一個(gè)常見(jiàn)需求是“租戶 A 的搜索消耗不能影響租戶 B”。如果所有租戶共用同一個(gè) API Key一旦某位客戶觸發(fā)大量搜索其他客戶的響應(yīng)速度就會(huì)下降甚至觸發(fā)服務(wù)商限流。建議在搜索網(wǎng)關(guān)上增加租戶維度控制把流量分開(kāi)。實(shí)現(xiàn)方式有兩種一是為每個(gè)大客戶申請(qǐng)獨(dú)立的 API Key在請(qǐng)求時(shí)根據(jù)租戶標(biāo)識(shí)選擇不同 Key二是在網(wǎng)關(guān)層維護(hù)配額池每個(gè)租戶有獨(dú)立的每分鐘請(qǐng)求數(shù)上限。前者更干凈但成本較高后者實(shí)現(xiàn)靈活能夠動(dòng)態(tài)調(diào)整。大客戶合同中通常會(huì)有 QPS 或月度調(diào)用量約束建議提前與服務(wù)商確認(rèn)配額并在網(wǎng)關(guān)層配置告警超過(guò)閾值的 80% 就提醒運(yùn)維。6.2 緩存策略與降級(jí)方案實(shí)時(shí)搜索雖然有實(shí)時(shí)性要求但并不是每個(gè)問(wèn)題都需要實(shí)時(shí)檢索。相同或相似的問(wèn)題在短時(shí)間內(nèi)的結(jié)果往往差別不大?？梢栽诰W(wǎng)關(guān)層加一層緩存例如把同一 query 在 5 分鐘內(nèi)的重復(fù)請(qǐng)求直接走緩存減輕下游壓力。但要注意涉及價(jià)格、政策、故障公告等高頻變化信息緩存時(shí)間要設(shè)置得短一些甚至不緩存。降級(jí)方案同樣重要。當(dāng)實(shí)時(shí)搜索服務(wù)不可用或超時(shí)時(shí)Decagon 至少要能退回默認(rèn)回答能力而不是直接報(bào)錯(cuò)。推薦的降級(jí)邏輯是捕獲搜索客戶端異常返回一個(gè)空結(jié)果Decagon 側(cè)如果拿到空結(jié)果就使用知識(shí)庫(kù)檢索結(jié)果或者回答“暫時(shí)無(wú)法獲取最新信息請(qǐng)稍后再試”。這樣雖然回答完整度下降但不會(huì)導(dǎo)致會(huì)話中斷客戶體驗(yàn)不會(huì)受到毀滅性打擊。6.3 日志、監(jiān)控與審計(jì)大客戶對(duì)接最容易被忽略的是日志審計(jì)。外部搜索請(qǐng)求涉及數(shù)據(jù)出域必須有完整的記錄。建議日志至少包含這些字段請(qǐng)求 ID、租戶 ID、用戶 ID、查詢內(nèi)容、請(qǐng)求時(shí)間、返回狀態(tài)、響應(yīng)耗時(shí)、引用數(shù)量、Token 消耗。查詢內(nèi)容涉及用戶隱私時(shí)需要做脫敏處理比如隱藏姓名和聯(lián)系方式。監(jiān)控指標(biāo)方面重點(diǎn)看搜索服務(wù)的成功率、平均耗時(shí)、超時(shí)率、限流次數(shù)。可以接入 Prometheus 或云監(jiān)控在搜索失敗率超過(guò) 5% 時(shí)觸發(fā)告警。審計(jì)日志則單獨(dú)存儲(chǔ)保留時(shí)間按照企業(yè)合規(guī)要求來(lái)定一般不少于 6 個(gè)月。這里要強(qiáng)調(diào)的是不要在業(yè)務(wù)日志里打印完整 API Key也不要把用戶的原文和搜索結(jié)果直接寫(xiě)入公共日志避免數(shù)據(jù)泄露。7. 常見(jiàn)問(wèn)題與排查清單問(wèn)題現(xiàn)象常見(jiàn)原因解決思路搜索接口一直超時(shí)網(wǎng)絡(luò)策略未放通或域名解析異常先 ping / telnet 確認(rèn)連通性再檢查代理和防火墻白名單返回 401 鑒權(quán)失敗API Key 配置錯(cuò)誤或已過(guò)期檢查環(huán)境變量和配置中心是否覆蓋最新 Key并到服務(wù)商后臺(tái)確認(rèn)有效期返回 429 頻次超限請(qǐng)求量超過(guò)套餐配額增加緩存降低重復(fù)請(qǐng)求或者在網(wǎng)關(guān)層排隊(duì)削峰Decagon 沒(méi)有觸發(fā)搜索工具提示詞未配置或工具未啟用檢查工具是否上線改用明確的 prompt 描述觸發(fā)條件答案引用來(lái)源為空搜索服務(wù)未返回 citation 字段或字段映射錯(cuò)誤查看原始返回日志調(diào)整標(biāo)準(zhǔn)化函數(shù)中的字段映射生產(chǎn)環(huán)境搜索正常但客戶會(huì)話中報(bào)錯(cuò)會(huì)話上下文中的 query 過(guò)長(zhǎng)或工具參數(shù)解析失敗檢查 Decagon 工具參數(shù)模板限制 query 最大長(zhǎng)度搜索回答與知識(shí)庫(kù)沖突實(shí)時(shí)結(jié)果可信度不高或時(shí)效性標(biāo)記不明確在提示詞中要求“優(yōu)先實(shí)時(shí)結(jié)果并標(biāo)注來(lái)源”必要時(shí)人工抽樣檢查排查時(shí)建議按“日志 → 復(fù)現(xiàn) → 定位 → 修復(fù)”的順序推進(jìn)。第一步查看搜索網(wǎng)關(guān)日志確認(rèn)請(qǐng)求是否到達(dá)下游第二步用一個(gè)公開(kāi)測(cè)試接口復(fù)現(xiàn)問(wèn)題第三步對(duì)比成功和失敗的請(qǐng)求參數(shù)通常能很快定位到是鑒權(quán)、參數(shù)還是網(wǎng)絡(luò)問(wèn)題最后再修改代碼或配置并在測(cè)試環(huán)境回歸。8. 最佳實(shí)踐與工程建議8.1 外部服務(wù)依賴要“可替換”把 Perplexity 實(shí)時(shí)搜索服務(wù)封裝在統(tǒng)一接口后面是降低替換成本的關(guān)鍵。不要在主業(yè)務(wù)代碼中直接調(diào)用第三方 SDK 的類和方法而是先定義自己的 SearchPort 接口然后用 PerplexityAdapter 實(shí)現(xiàn)。這樣未來(lái)如果要換成其他搜索服務(wù)商只需要新增一個(gè) Adapter不用改動(dòng) Decagon 側(cè)的任何代碼。接口設(shè)計(jì)可以參考下面這個(gè)最小樣例。class SearchPort: def search(self, query: str) - Dict[str, Any]: raise NotImplementedError class PerplexityAdapter(SearchPort): def search(self, query: str) - Dict[str, Any]: raw search_real_time(query) return normalize_search_result(raw)這種設(shè)計(jì)也方便編寫(xiě)單元測(cè)試。測(cè)試一個(gè)搜索服務(wù)本身就是外部依賴如果直接打真實(shí)接口測(cè)試會(huì)慢且不穩(wěn)定。有了接口抽象我們可以用 Mock 對(duì)象模擬搜索結(jié)果快速驗(yàn)證 Decagon 側(cè)的業(yè)務(wù)邏輯。8.2 密鑰管理和敏感信息保護(hù)無(wú)論項(xiàng)目規(guī)模大小密鑰管理都要當(dāng)成最高優(yōu)先級(jí)。建議遵循最小權(quán)限原則只有搜索網(wǎng)關(guān)服務(wù)需要調(diào)用外部搜索其他服務(wù)一律不保存搜索 API Key。如果使用 Kubernetes把 Key 放在 Secret 中并配置 RBAC 權(quán)限只允許目標(biāo)服務(wù)讀取如果使用云服務(wù)器可以使用云廠商的密鑰管理服務(wù)。同時(shí)要定期輪換 API Key比如每 90 天輪換一次。輪換期間新舊 Key 可以并行存在一段時(shí)間避免更新配置瞬間服務(wù)不可用。這一條在對(duì)接大客戶時(shí)尤其重要因?yàn)榇罂蛻舻陌踩珗F(tuán)隊(duì)會(huì)定期檢查密鑰管理制度如果你能主動(dòng)展示輪換策略會(huì)更容易通過(guò)合規(guī)評(píng)審。8.3 成本控制與性能平衡實(shí)時(shí)搜索服務(wù)通常按調(diào)用量或 Token 計(jì)費(fèi)成本可能成為大客戶項(xiàng)目中的敏感話題?？刂瞥杀镜乃悸分饕兴膫€(gè)方向一是加緩存減少重復(fù)調(diào)用二是設(shè)置 query 復(fù)雜度限制避免無(wú)意義的長(zhǎng)查詢?nèi)窃跇I(yè)務(wù)層設(shè)計(jì)觸發(fā)條件只對(duì)確實(shí)需要最新信息的問(wèn)題調(diào)用搜索四是定期分析搜索日志把高頻且變化不大的問(wèn)題沉淀到知識(shí)庫(kù)逐步減少對(duì)外部搜索的依賴。性能方面除了在客戶端設(shè)置超時(shí)還要在網(wǎng)關(guān)層配置并發(fā)限制。服務(wù)商一般會(huì)有 QPS 上限超過(guò)后直接返回 429。如果我們內(nèi)部不限制并發(fā)而是讓所有請(qǐng)求同時(shí)涌向搜索服務(wù)很容易觸發(fā)限流。一個(gè)好的做法是在網(wǎng)關(guān)層引入信號(hào)量或令牌桶把最大并發(fā)控制在一個(gè)安全值例如 50超出的請(qǐng)求直接排隊(duì)或失敗降級(jí)。8.4 上線前的大客戶驗(yàn)收清單在正式交付給大客戶前建議對(duì)照以下清單做一輪內(nèi)部驗(yàn)收是否確認(rèn)了生產(chǎn)環(huán)境的 API Key 和網(wǎng)絡(luò)白名單是否完成了權(quán)限分離測(cè)試環(huán)境與生產(chǎn)環(huán)境使用不同 Key是否驗(yàn)證了搜索超時(shí)和搜索服務(wù)不可用時(shí)的降級(jí)鏈路是否配置了審計(jì)日志并能按租戶維度檢索是否設(shè)置了大客戶配額和異常告警是否在 Decagon 后臺(tái)完成了工具命名和提示詞模板的審核是否準(zhǔn)備了故障應(yīng)急預(yù)案明確負(fù)責(zé)人和回滾方式。這份清單并不復(fù)雜但很多團(tuán)隊(duì)在項(xiàng)目交付時(shí)因?yàn)榧庇谏暇€跳過(guò)了其中一兩項(xiàng)最后在客戶驗(yàn)收階段被反復(fù)打回。提前把驗(yàn)收標(biāo)準(zhǔn)確定好反而能加快整體交付速度。9. 總結(jié)與后續(xù)優(yōu)化方向至此我們完整梳理了 Decagon 接入 Perplexity 實(shí)時(shí)搜索服務(wù)服務(wù)大客戶的全過(guò)程從需求背景、方案設(shè)計(jì)到代碼實(shí)現(xiàn)、生產(chǎn)配置都給出了可落地的參考。核心思路可以概括為三點(diǎn)第一通過(guò)標(biāo)準(zhǔn)化客戶端封裝外部搜索服務(wù)降低替換成本第二通過(guò)工具調(diào)用和提示詞模板讓 Decagon 在合適的時(shí)機(jī)使用實(shí)時(shí)搜索第三通過(guò)多租戶隔離、緩存、限流、審計(jì)等工程手段滿足大客戶在安全、成本和可靠性方面的要求。如果你正在負(fù)責(zé)類似的實(shí)時(shí)搜索集成項(xiàng)目建議先不要急著寫(xiě)代碼而是和客戶確認(rèn)清楚幾個(gè)問(wèn)題實(shí)時(shí)搜索的使用場(chǎng)景是什么數(shù)據(jù)出域是否合規(guī)調(diào)用配額和預(yù)算上限是多少失敗的降級(jí)策略由誰(shuí)批準(zhǔn)。把這些問(wèn)題聊清楚后續(xù)開(kāi)發(fā)會(huì)順暢很多。實(shí)時(shí)搜索技術(shù)本身還在快速迭代接口參數(shù)和模型能力都會(huì)不斷變化但只要我們把架構(gòu)設(shè)計(jì)的足夠靈活保持對(duì)變化的適應(yīng)能力就能在大客戶服務(wù)中持續(xù)提供高質(zhì)量的支持。希望這篇實(shí)戰(zhàn)筆記能給正在做相關(guān)系統(tǒng)的你帶來(lái)一些可復(fù)用的思路。 AI客服集成實(shí)時(shí)搜索：Decagon對(duì)接Perplexity實(shí)戰(zhàn)指南
在很多企業(yè)級(jí)智能客服項(xiàng)目中模型回答的“時(shí)效性”始終是一個(gè)繞不開(kāi)的話題?？蛻魰?huì)問(wèn)產(chǎn)品價(jià)格是否調(diào)整、系統(tǒng)當(dāng)前是否故障、附近網(wǎng)點(diǎn)是否還在營(yíng)業(yè)這類問(wèn)題需要依賴最新信息才能給出可靠答案。如果只依靠模型的靜態(tài)訓(xùn)練數(shù)據(jù)回答很容易過(guò)時(shí)甚至在大客戶面前留下不專業(yè)的印象。為了解決這個(gè)問(wèn)題業(yè)內(nèi)常用做法是在 AI 客服平臺(tái)里接入實(shí)時(shí)搜索服務(wù)把最新搜索結(jié)果作為回答依據(jù)。本文就圍繞 Decagon 接入 Perplexity 實(shí)時(shí)搜索服務(wù)這一大客戶集成場(chǎng)景梳理從需求分析、方案設(shè)計(jì)到代碼落地、生產(chǎn)排錯(cuò)的完整過(guò)程希望給正在做類似對(duì)接的團(tuán)隊(duì)提供一份可參考的工程筆記。1. 背景與核心概念1.1 為什么大客戶需要實(shí)時(shí)搜索能力大型企業(yè)客戶的客服場(chǎng)景通常對(duì)準(zhǔn)確率和時(shí)效性要求非常高。一個(gè)集團(tuán)客戶可能每天收到上千條咨詢其中不少問(wèn)題涉及當(dāng)天發(fā)生的變更比如價(jià)格策略、物流公告、產(chǎn)品版本發(fā)布、系統(tǒng)維護(hù)通知等。傳統(tǒng)做法是把資料預(yù)先導(dǎo)入知識(shí)庫(kù)再通過(guò)向量檢索找答案但這類方式有兩個(gè)明顯問(wèn)題第一知識(shí)庫(kù)更新依賴人工上傳響應(yīng)速度慢第二一些外部信息比如競(jìng)品動(dòng)態(tài)、行業(yè)政策、實(shí)時(shí)天氣根本無(wú)法提前入庫(kù)。實(shí)時(shí)搜索能力恰好能補(bǔ)上這個(gè)短板讓客服機(jī)器人在回答前主動(dòng)檢索最新網(wǎng)頁(yè)信息再結(jié)合模型的語(yǔ)言組織能力生成答案既保留了自然對(duì)話體驗(yàn)又讓回答有據(jù)可查。更重要的是大客戶在采購(gòu)企業(yè)級(jí)服務(wù)時(shí)會(huì)格外關(guān)注答案的“可信度”。他們不會(huì)接受一個(gè)只會(huì)說(shuō)“可能”“大概”的機(jī)器人而是希望看到回答附帶來(lái)源鏈接和更新時(shí)間。Perplexity 這類實(shí)時(shí)搜索服務(wù)恰好能提供帶引用來(lái)源的搜索結(jié)果Decagon 作為客戶支持自動(dòng)化平臺(tái)則負(fù)責(zé)把搜索能力編排到具體的客服會(huì)話流程中。兩者結(jié)合后客服機(jī)器人既能理解客戶意圖又能實(shí)時(shí)獲取外部世界的最新變化最終在保證體驗(yàn)的同時(shí)提升解決率。1.2 Decagon 在集成中扮演的角色Decagon 是一個(gè)面向企業(yè)級(jí)客戶的 AI 客服支持平臺(tái)它的核心價(jià)值在于把大語(yǔ)言模型、業(yè)務(wù)系統(tǒng)、客服工作流和自動(dòng)化工具編排在一起。簡(jiǎn)單理解Decagon 是“大腦和指揮中心”負(fù)責(zé)理解用戶消息、判斷意圖、調(diào)用工具、組織回復(fù)同時(shí)還要兼顧多輪對(duì)話、工單生成、人工接管等業(yè)務(wù)邏輯。在大客戶接入項(xiàng)目中Decagon 通常已經(jīng)具備穩(wěn)定的會(huì)話入口、用戶身份體系、工單系統(tǒng)和知識(shí)庫(kù)。接入實(shí)時(shí)搜索時(shí)我們不需要把所有搜索邏輯寫(xiě)死在業(yè)務(wù)代碼里而是把實(shí)時(shí)搜索封裝成一個(gè)“工具服務(wù)”由 Decagon 在需要時(shí)調(diào)用。這種解耦方式對(duì)項(xiàng)目落地非常關(guān)鍵。一方面實(shí)時(shí)搜索服務(wù)的接口和邏輯可以獨(dú)立升級(jí)不會(huì)影響 Decagon 本身的穩(wěn)定性另一方面大客戶往往有嚴(yán)格的安全審計(jì)要求把搜索服務(wù)獨(dú)立出來(lái)能更清晰地控制數(shù)據(jù)流向記錄每一次外部請(qǐng)求。所以在設(shè)計(jì)階段建議把 Decagon 與實(shí)時(shí)搜索服務(wù)放在兩個(gè)不同模塊中盡量通過(guò)標(biāo)準(zhǔn) REST 接口或消息隊(duì)列通信而不是直接把搜索邏輯嵌入到會(huì)話處理的主鏈路里。1.3 Perplexity 實(shí)時(shí)搜索服務(wù)的定位Perplexity 是當(dāng)前比較有代表性的 AI 實(shí)時(shí)搜索服務(wù)它擅長(zhǎng)的正是“搜索 生成”的組合根據(jù)用戶輸入的關(guān)鍵詞或問(wèn)題實(shí)時(shí)檢索互聯(lián)網(wǎng)內(nèi)容再把檢索結(jié)果整理成帶引用的回答。對(duì)企業(yè)級(jí)集成來(lái)說(shuō)Perplexity 的價(jià)值不僅是返回一段答案而是能把“信息來(lái)源”一起帶回來(lái)這正好滿足了大客戶對(duì)答案可追溯的訴求。在實(shí)際接入時(shí)我們需要把它看成一種“外部數(shù)據(jù)源”而不是一個(gè)黑盒聊天機(jī)器人。需要注意的是Perplexity 的接口參數(shù)、鑒權(quán)方式、限流策略可能在不斷更新本文不會(huì)把某個(gè)固定版本的細(xì)節(jié)作為唯一標(biāo)準(zhǔn)。技術(shù)團(tuán)隊(duì)拿到授權(quán)后應(yīng)以服務(wù)商提供的最新 API 文檔為準(zhǔn)。我們?cè)谶@篇文章中更多是分享一套通用的集成思路如何配置密鑰、如何封裝請(qǐng)求、如何解析返回、如何做緩存和降級(jí)。只要掌握這些套路即使接口細(xì)節(jié)變化也能快速適配。2. 大客戶接入方案整體設(shè)計(jì)2.1 接入流程概覽大客戶接入實(shí)時(shí)搜索服務(wù)不能一上來(lái)就寫(xiě)代碼。建議先梳理一條完整的數(shù)據(jù)鏈路確保每個(gè)環(huán)節(jié)的責(zé)任邊界清晰。整體流程可以拆成六個(gè)步驟第一步在服務(wù)商后臺(tái)申請(qǐng)實(shí)時(shí)搜索服務(wù)的訪問(wèn)憑證第二步在企業(yè)內(nèi)部網(wǎng)絡(luò)規(guī)劃中放通與搜索服務(wù)之間的訪問(wèn)通道第三步開(kāi)發(fā)一個(gè)標(biāo)準(zhǔn)化的搜索客戶端統(tǒng)一管理鑒權(quán)、請(qǐng)求、超時(shí)和重試第四步把搜索客戶端封裝成 Decagon 可調(diào)用的工具接口第五步在 Decagon 會(huì)話流程中配置觸發(fā)條件和提示詞模板第六步上線前完成權(quán)限、日志、審計(jì)和熔斷策略的驗(yàn)證。這個(gè)流程看起來(lái)簡(jiǎn)單但真正執(zhí)行時(shí)經(jīng)?？ㄔ诰W(wǎng)絡(luò)策略和賬號(hào)權(quán)限上。大客戶環(huán)境通常有嚴(yán)格的防火墻規(guī)則哪些部門可以調(diào)用外部 API哪些環(huán)境可以存儲(chǔ)密鑰都需要提前確認(rèn)。另外建議在測(cè)試環(huán)境先打通一條最小鏈路用固定問(wèn)題驗(yàn)證搜索返回、結(jié)果解析和 answer 組裝再逐步放開(kāi)到生產(chǎn)環(huán)境。2.2 網(wǎng)絡(luò)與安全設(shè)計(jì)實(shí)時(shí)搜索服務(wù)通常屬于外部 API企業(yè)內(nèi)部服務(wù)調(diào)用時(shí)需要經(jīng)過(guò)安全邊界。常見(jiàn)方式有兩種一種是直接通過(guò)公網(wǎng)訪問(wèn)使用 API Key 或 Token 鑒權(quán)另一種是在企業(yè)內(nèi)部部署代理網(wǎng)關(guān)由網(wǎng)關(guān)統(tǒng)一轉(zhuǎn)發(fā)外部請(qǐng)求方便在網(wǎng)關(guān)層做審計(jì)、限流和脫敏。對(duì)大客戶項(xiàng)目更推薦后者因?yàn)榇砭W(wǎng)關(guān)可以隱藏內(nèi)部服務(wù)結(jié)構(gòu)也方便統(tǒng)一控制訪問(wèn)范圍。安全設(shè)計(jì)上必須重點(diǎn)關(guān)注密鑰保管。不要把 API Key 直接寫(xiě)在代碼里更不要提交到 Git 倉(cāng)庫(kù)。推薦使用環(huán)境變量或配置中心管理密鑰并在服務(wù)啟動(dòng)時(shí)校驗(yàn)密鑰是否存在。如果是 Kubernetes 環(huán)境可以使用 Secret 對(duì)象保存如果是 Spring Cloud 體系可以使用配置中心加解密。網(wǎng)絡(luò)層面如果服務(wù)商支持 IP 白名單建議按生產(chǎn)環(huán)境出口 IP 配置白名單降低密鑰泄露后被濫用的風(fēng)險(xiǎn)。2.3 數(shù)據(jù)流與時(shí)序設(shè)計(jì)一次完整的實(shí)時(shí)搜索會(huì)話可以這樣描述客戶向 Decagon 發(fā)起咨詢Decagon 判斷當(dāng)前問(wèn)題需要外部最新信息Decagon 調(diào)用企業(yè)內(nèi)部搜索網(wǎng)關(guān)搜索網(wǎng)關(guān)向 Perplexity 服務(wù)發(fā)起實(shí)時(shí)搜索請(qǐng)求搜索服務(wù)返回答案和引用來(lái)源搜索網(wǎng)關(guān)把結(jié)果標(biāo)準(zhǔn)化后返回給 DecagonDecagon 結(jié)合業(yè)務(wù)上下文生成最終回復(fù)并把引用鏈接展示給客戶。整個(gè)過(guò)程中Decagon 只負(fù)責(zé)流程編排不直接感知 Perplexity 的內(nèi)部實(shí)現(xiàn)。為了便于排查問(wèn)題每次調(diào)用都要生成唯一的請(qǐng)求 ID并貫穿整個(gè)鏈路。建議至少記錄以下字段調(diào)用時(shí)間、請(qǐng)求 ID、客戶租戶 ID、查詢內(nèi)容、返回狀態(tài)、耗時(shí)、引用來(lái)源數(shù)量。大客戶審計(jì)時(shí)往往需要提供某一時(shí)間段內(nèi)的外部搜索調(diào)用明細(xì)如果我們沒(méi)有做日志事后補(bǔ)數(shù)據(jù)會(huì)非常痛苦。所以在方案設(shè)計(jì)階段就要把審計(jì)日志當(dāng)成核心功能而不是后期補(bǔ)丁。3. 環(huán)境準(zhǔn)備與前置條件3.1 賬號(hào)與權(quán)限準(zhǔn)備接入前需要確認(rèn)三個(gè)賬號(hào)維度實(shí)時(shí)搜索服務(wù)商賬號(hào)、Decagon 管理后臺(tái)賬號(hào)、企業(yè)內(nèi)部用于部署服務(wù)的云平臺(tái)或服務(wù)器賬號(hào)。實(shí)時(shí)搜索服務(wù)商賬號(hào)通常要申請(qǐng) API Key部分企業(yè)級(jí)套餐還會(huì)提供專屬 endpoint 和更高配額。Decagon 管理后臺(tái)需要具備工具配置和會(huì)話流編輯權(quán)限。企業(yè)內(nèi)部服務(wù)器賬號(hào)則需具備部署程序、讀取環(huán)境變量、寫(xiě)入日志的權(quán)限。這里要特別提醒大客戶項(xiàng)目建議使用獨(dú)立的服務(wù)賬號(hào)不要用個(gè)人賬號(hào)申請(qǐng)密鑰。這樣即使員工離職也可以通過(guò)回收服務(wù)賬號(hào)權(quán)限來(lái)保證系統(tǒng)安全。同時(shí)在服務(wù)商后臺(tái)最好配置多個(gè) Key 分別用于測(cè)試環(huán)境和生產(chǎn)環(huán)境避免測(cè)試流量影響生產(chǎn)配額也方便成本核算。3.2 開(kāi)發(fā)語(yǔ)言與依賴版本本文的示例代碼以 Python 和 Java 為主因?yàn)檫@兩種語(yǔ)言在企業(yè)服務(wù)端最常用。Python 示例使用 requests 作為 HTTP 客戶端依賴簡(jiǎn)潔容易理解Java 示例使用 Spring Boot 的 RestTemplate方便接入現(xiàn)有微服務(wù)體系。需要說(shuō)明的是requests 和 RestTemplate 只是工具不是唯一選擇你可以換成 httpx、OkHttp、WebClient 等核心思路不變。版本方面沒(méi)有強(qiáng)制要求建議使用較為穩(wěn)定的版本即可。如果你的項(xiàng)目是 Python 3.9直接安裝 requests 最新穩(wěn)定版如果是 Spring Boot 2.7RestTemplate 是內(nèi)置能力不需要額外依賴。關(guān)鍵是確認(rèn)你的應(yīng)用服務(wù)器能夠訪問(wèn)到實(shí)時(shí)搜索服務(wù)域名否則代碼寫(xiě)得再完善也會(huì)在連接階段超時(shí)。3.3 示例項(xiàng)目結(jié)構(gòu)為了演示方便我們規(guī)劃一個(gè)最小的項(xiàng)目結(jié)構(gòu)。后端服務(wù)提供兩個(gè)能力一個(gè)是標(biāo)準(zhǔn)的搜索 REST 接口供 Decagon 調(diào)用另一個(gè)是內(nèi)部工具函數(shù)用于測(cè)試和調(diào)試。search-service/ ├── src/ │ ├── main/ │ │ ├── java/com/example/search/ │ │ │ ├── SearchController.java │ │ │ ├── SearchClient.java │ │ │ ├── SearchRequest.java │ │ │ └── SearchResponse.java │ │ └── resources/application.yml │ └── test/ ├── python-demo/ │ ├── search_client.py │ ├── normalize_result.py │ └── .env.example └── README.mdPython 部分主要用來(lái)說(shuō)明客戶端封裝思路Java 部分用來(lái)展示如何把搜索接口暴露給 Decagon 去調(diào)用。實(shí)際項(xiàng)目中不需要完全照搬這個(gè)結(jié)構(gòu)但建議把“客戶端封裝”和“接口暴露”分層便于后期維護(hù)。4. 核心代碼實(shí)現(xiàn)封裝實(shí)時(shí)搜索客戶端4.1 配置管理無(wú)論使用哪種語(yǔ)言第一步都是把搜索服務(wù)的 endpoint 和 API Key 放到配置中。不要硬編碼。Python 項(xiàng)目可以使用.env文件配合os.getenv讀取Java 項(xiàng)目可以放在application.yml中并通過(guò)Value注入。下面是一個(gè).env.example示例實(shí)際使用時(shí)應(yīng)復(fù)制為.env并填入真實(shí)值# .env.example PERPLEXITY_API_URLhttps://your-search-endpoint.example.com/v1/query PERPLEXITY_API_KEYsk-xxxxxxxxxxxxxxxx SEARCH_TIMEOUT_MS30000 SEARCH_MAX_TOKENS600對(duì)應(yīng)的 Python 讀取代碼import os PERPLEXITY_API_URL os.getenv(PERPLEXITY_API_URL, ) PERPLEXITY_API_KEY os.getenv(PERPLEXITY_API_KEY, ) SEARCH_TIMEOUT int(os.getenv(SEARCH_TIMEOUT_MS, 30000)) / 1000 SEARCH_MAX_TOKENS int(os.getenv(SEARCH_MAX_TOKENS, 600))這里的默認(rèn)值只做演示企業(yè)環(huán)境應(yīng)通過(guò)環(huán)境變量強(qiáng)制注入不要在代碼中保留默認(rèn) Key。如果啟動(dòng)時(shí)發(fā)現(xiàn) Key 為空可以直接拋異常避免帶著錯(cuò)誤配置上線。4.2 請(qǐng)求封裝Python 示例實(shí)時(shí)搜索服務(wù)的 HTTP 調(diào)用通常遵循 REST 風(fēng)格方法為 POST請(qǐng)求體為 JSON。下面這段代碼演示了如何把查詢文本、最大返回長(zhǎng)度等參數(shù)發(fā)送到搜索服務(wù)。請(qǐng)注意示例中的 URL 是占位地址真實(shí)項(xiàng)目務(wù)必替換為服務(wù)方提供的 endpoint。import os import requests from typing import Dict, Optional PERPLEXITY_API_URL os.getenv(PERPLEXITY_API_URL, ) PERPLEXITY_API_KEY os.getenv(PERPLEXITY_API_KEY, ) def search_real_time(query: str, max_tokens: int 600) - Optional[Dict]: 調(diào)用 Perplexity 實(shí)時(shí)搜索接口。 :param query: 客戶問(wèn)題或搜索關(guān)鍵詞 :param max_tokens: 搜索生成結(jié)果的最大長(zhǎng)度 :return: 解析后的 JSON 字典失敗時(shí)返回 None if not PERPLEXITY_API_URL or not PERPLEXITY_API_KEY: raise RuntimeError(搜索服務(wù)地址或 API Key 未配置) headers { Authorization: fBearer {PERPLEXITY_API_KEY}, Content-Type: application/json, } payload { query: query, max_tokens: max_tokens, stream: False, } try: resp requests.post( PERPLEXITY_API_URL, headersheaders, jsonpayload, timeout30 ) resp.raise_for_status() return resp.json() except requests.exceptions.Timeout: print([search_real_time] 請(qǐng)求超時(shí)請(qǐng)稍后重試) except requests.exceptions.RequestException as e: print(f[search_real_time] 請(qǐng)求失敗: {e}) return None這段代碼有幾個(gè)關(guān)鍵點(diǎn)。第一使用Authorization: Bearer傳遞密鑰這是最常見(jiàn)的 HTTP API 鑒權(quán)方式如果你的服務(wù)商要求自定義頭字段只需要調(diào)整 headers 字典。第二設(shè)置了 30 秒超時(shí)避免下游異常導(dǎo)致整個(gè)業(yè)務(wù)線程長(zhǎng)時(shí)間阻塞。第三用raise_for_status()統(tǒng)一處理 4xx 和 5xx 錯(cuò)誤方便上層感知調(diào)用失敗。實(shí)際開(kāi)發(fā)中建議把超時(shí)時(shí)間放到配置里并區(qū)分“連接超時(shí)”和“讀取超時(shí)”。4.3 結(jié)果標(biāo)準(zhǔn)化Python 示例實(shí)時(shí)搜索服務(wù)返回的 JSON 結(jié)構(gòu)可能比較雜亂不同接口返回的字段名也可能不同。為了讓 Decagon 側(cè)不感知下游變化我們要在客戶端內(nèi)部做一次標(biāo)準(zhǔn)化轉(zhuǎn)換。假設(shè)搜索返回結(jié)果中包含答案文本、引用列表和請(qǐng)求消耗的 token 數(shù)我們可以統(tǒng)一成下面這種結(jié)構(gòu)。from typing import Dict, List, Any def normalize_search_result(raw: Dict[str, Any]) - Dict[str, Any]: 將搜索接口原始返回轉(zhuǎn)換為標(biāo)準(zhǔn)化結(jié)構(gòu)。 # 這里需要根據(jù)真實(shí)接口返回做字段映射下面是示例邏輯 answer raw.get(answer) or raw.get(text) or raw.get(result) or citations raw.get(citations) or raw.get(sources) or [] normalized { answer: answer, citations: [], query: raw.get(query, ), created_at: raw.get(created_at) or raw.get(timestamp, ), } for item in citations: if isinstance(item, str): normalized[citations].append({url: item, title: item}) elif isinstance(item, dict): normalized[citations].append({ url: item.get(url, ), title: item.get(title, item.get(url, )), }) return normalized標(biāo)準(zhǔn)化層最大的價(jià)值是屏蔽下游差異。例如服務(wù)商某天調(diào)整了返回字段從answer改成了text我們只需要修改標(biāo)準(zhǔn)化函數(shù)Decagon 的業(yè)務(wù)代碼完全不用動(dòng)。這種防御式編程思路在對(duì)接外部服務(wù)時(shí)非常重要尤其是大客戶項(xiàng)目版本升級(jí)頻繁接口小調(diào)整很難避免。4.4 Java 側(cè)接口暴露RestTemplate 示例如果企業(yè)技術(shù)棧是 Java通常會(huì)把搜索能力封裝成 Spring Boot 服務(wù)。下面展示一個(gè)最簡(jiǎn)單的 SearchClient它使用 RestTemplate 發(fā)送 POST 請(qǐng)求并通過(guò) DTO 接收返回。這里同樣是演示思路接口地址和 DTO 字段需要根據(jù)實(shí)際協(xié)議設(shè)計(jì)。// SearchClient.java import org.springframework.beans.factory.annotation.Value; import org.springframework.http.*; import org.springframework.stereotype.Component; import org.springframework.web.client.RestTemplate; import java.util.HashMap; import java.util.Map; Component public class SearchClient { private final RestTemplate restTemplate new RestTemplate(); Value(${perplexity.api-url}) private String apiUrl; Value(${perplexity.api-key}) private String apiKey; public SearchResponse search(String query) { HttpHeaders headers new HttpHeaders(); headers.setBearerAuth(apiKey); headers.setContentType(MediaType.APPLICATION_JSON); MapString, Object body new HashMap(); body.put(query, query); HttpEntityMapString, Object requestEntity new HttpEntity(body, headers); ResponseEntitySearchResponse response restTemplate.exchange( apiUrl, HttpMethod.POST, requestEntity, SearchResponse.class ); return response.getBody(); } }Java 版本的核心思路和 Python 一致都是“密鑰放配置 請(qǐng)求封裝 超時(shí)處理”。在實(shí)際項(xiàng)目中建議把 RestTemplate 換成帶連接池和超時(shí)配置的實(shí)例并接入公司的鏈路追蹤組件。SearchResponse 的字段可以根據(jù)接口返回定義如果你不想定義實(shí)體也可以用JsonNode接收再手動(dòng)標(biāo)準(zhǔn)化。5. 將搜索能力集成為 Decagon 工具5.1 工具調(diào)用Tool Calling思路Decagon 這類 AI 客服平臺(tái)通常會(huì)提供 tool calling 機(jī)制。也就是說(shuō)當(dāng)大模型判斷用戶問(wèn)題需要外部信息時(shí)會(huì)生成一個(gè)“調(diào)用實(shí)時(shí)搜索工具”的動(dòng)作平臺(tái)再根據(jù)這個(gè)動(dòng)作去請(qǐng)求搜索服務(wù)。因此我們不需要修改 Decagon 的底層模型只需要在控制臺(tái)或代碼中注冊(cè)一個(gè)搜索工具并明確工具的入?yún)⒑统鰠?。以常?jiàn)的配置方式為例我們的搜索工具可以聲明成工具名稱為real_time_search參數(shù)是querystring必填輸出是一段標(biāo)準(zhǔn)化的 JSON。Decagon 收到用戶問(wèn)題后會(huì)通過(guò)提示詞判斷是否觸發(fā)該工具。這種設(shè)計(jì)的好處是搜索能力可以被復(fù)用無(wú)論用戶問(wèn)的是售后政策、物流狀態(tài)還是競(jìng)品對(duì)比只要模型認(rèn)為需要最新外部信息都會(huì)自動(dòng)調(diào)用同一套搜索服務(wù)。5.2 提示詞模板設(shè)計(jì)提示詞是決定搜索效果的關(guān)鍵部分。如果提示詞寫(xiě)得太簡(jiǎn)單模型可能不知道該在什么時(shí)候搜索或者把搜索結(jié)果和自身知識(shí)混在一起。建議給 Decagon 配置類似下面這種提示詞模板。你是一位企業(yè)級(jí)客服助手。你的任務(wù)是根據(jù)用戶問(wèn)題給出準(zhǔn)確、禮貌、有依據(jù)的回答。 使用工具 real_time_search 的條件 1. 用戶詢問(wèn)的內(nèi)容可能隨時(shí)間變化例如價(jià)格、政策、庫(kù)存、公告、新聞。 2. 用戶要求提供最新信息例如“現(xiàn)在”“最新”“今天”等。 3. 你需要補(bǔ)充訓(xùn)練數(shù)據(jù)中沒(méi)有覆蓋的外部信息。 使用工具時(shí)請(qǐng)遵循以下要求 - 根據(jù)用戶問(wèn)題生成簡(jiǎn)潔的 query。 - 等待搜索結(jié)果返回后優(yōu)先使用搜索結(jié)果組織答案。 - 在答案中標(biāo)注引用來(lái)源使用引用編號(hào)或鏈接。 - 如果搜索結(jié)果為空或與問(wèn)題不相關(guān)需要明確告訴用戶暫時(shí)無(wú)法找到可靠信息。這段模板既指導(dǎo)了大模型何時(shí)調(diào)用工具也規(guī)范了答案輸出格式。大客戶對(duì)回復(fù)風(fēng)格通常有嚴(yán)格要求網(wǎng)上可以搜到引用來(lái)源但語(yǔ)言仍需保持克制和專業(yè)不能因?yàn)樗阉鹘Y(jié)果中包含營(yíng)銷詞匯就把客服回復(fù)變成廣告文案。5.3 流式輸出與引用展示大客戶場(chǎng)景中用戶體驗(yàn)要求較高回答最好能流式輸出讓客戶不用等待太久。但實(shí)時(shí)搜索本身有網(wǎng)絡(luò)耗時(shí)通常不會(huì)直接對(duì)整個(gè) answer 做流式處理而是先快速返回“正在搜索最新信息……”的提示再在后臺(tái)完成搜索后將搜索結(jié)果作為下一輪消息返回。這樣體驗(yàn)更順暢。引用展示也需要設(shè)計(jì)好。普通搜索工具返回的 citations 是 URL 列表但 Decagon 頁(yè)面展示時(shí)可能需要在答案末尾顯示來(lái)源鏈接?？蛻舳嗽跇?biāo)準(zhǔn)化結(jié)果時(shí)要保留 citations 的原始順序并為每一條生成短標(biāo)題。如果鏈接被截?cái)嘀辽俳o出域名方便客戶判斷來(lái)源可信度。6. 大客戶場(chǎng)景的進(jìn)階配置6.1 多租戶隔離與配額管理服務(wù)多個(gè)大客戶時(shí)一個(gè)常見(jiàn)需求是“租戶 A 的搜索消耗不能影響租戶 B”。如果所有租戶共用同一個(gè) API Key一旦某位客戶觸發(fā)大量搜索其他客戶的響應(yīng)速度就會(huì)下降甚至觸發(fā)服務(wù)商限流。建議在搜索網(wǎng)關(guān)上增加租戶維度控制把流量分開(kāi)。實(shí)現(xiàn)方式有兩種一是為每個(gè)大客戶申請(qǐng)獨(dú)立的 API Key在請(qǐng)求時(shí)根據(jù)租戶標(biāo)識(shí)選擇不同 Key二是在網(wǎng)關(guān)層維護(hù)配額池每個(gè)租戶有獨(dú)立的每分鐘請(qǐng)求數(shù)上限。前者更干凈但成本較高后者實(shí)現(xiàn)靈活能夠動(dòng)態(tài)調(diào)整。大客戶合同中通常會(huì)有 QPS 或月度調(diào)用量約束建議提前與服務(wù)商確認(rèn)配額并在網(wǎng)關(guān)層配置告警超過(guò)閾值的 80% 就提醒運(yùn)維。6.2 緩存策略與降級(jí)方案實(shí)時(shí)搜索雖然有實(shí)時(shí)性要求但并不是每個(gè)問(wèn)題都需要實(shí)時(shí)檢索。相同或相似的問(wèn)題在短時(shí)間內(nèi)的結(jié)果往往差別不大?？梢栽诰W(wǎng)關(guān)層加一層緩存例如把同一 query 在 5 分鐘內(nèi)的重復(fù)請(qǐng)求直接走緩存減輕下游壓力。但要注意涉及價(jià)格、政策、故障公告等高頻變化信息緩存時(shí)間要設(shè)置得短一些甚至不緩存。降級(jí)方案同樣重要。當(dāng)實(shí)時(shí)搜索服務(wù)不可用或超時(shí)時(shí)Decagon 至少要能退回默認(rèn)回答能力而不是直接報(bào)錯(cuò)。推薦的降級(jí)邏輯是捕獲搜索客戶端異常返回一個(gè)空結(jié)果Decagon 側(cè)如果拿到空結(jié)果就使用知識(shí)庫(kù)檢索結(jié)果或者回答“暫時(shí)無(wú)法獲取最新信息請(qǐng)稍后再試”。這樣雖然回答完整度下降但不會(huì)導(dǎo)致會(huì)話中斷客戶體驗(yàn)不會(huì)受到毀滅性打擊。6.3 日志、監(jiān)控與審計(jì)大客戶對(duì)接最容易被忽略的是日志審計(jì)。外部搜索請(qǐng)求涉及數(shù)據(jù)出域必須有完整的記錄。建議日志至少包含這些字段請(qǐng)求 ID、租戶 ID、用戶 ID、查詢內(nèi)容、請(qǐng)求時(shí)間、返回狀態(tài)、響應(yīng)耗時(shí)、引用數(shù)量、Token 消耗。查詢內(nèi)容涉及用戶隱私時(shí)需要做脫敏處理比如隱藏姓名和聯(lián)系方式。監(jiān)控指標(biāo)方面重點(diǎn)看搜索服務(wù)的成功率、平均耗時(shí)、超時(shí)率、限流次數(shù)。可以接入 Prometheus 或云監(jiān)控在搜索失敗率超過(guò) 5% 時(shí)觸發(fā)告警。審計(jì)日志則單獨(dú)存儲(chǔ)保留時(shí)間按照企業(yè)合規(guī)要求來(lái)定一般不少于 6 個(gè)月。這里要強(qiáng)調(diào)的是不要在業(yè)務(wù)日志里打印完整 API Key也不要把用戶的原文和搜索結(jié)果直接寫(xiě)入公共日志避免數(shù)據(jù)泄露。7. 常見(jiàn)問(wèn)題與排查清單問(wèn)題現(xiàn)象常見(jiàn)原因解決思路搜索接口一直超時(shí)網(wǎng)絡(luò)策略未放通或域名解析異常先 ping / telnet 確認(rèn)連通性再檢查代理和防火墻白名單返回 401 鑒權(quán)失敗API Key 配置錯(cuò)誤或已過(guò)期檢查環(huán)境變量和配置中心是否覆蓋最新 Key并到服務(wù)商后臺(tái)確認(rèn)有效期返回 429 頻次超限請(qǐng)求量超過(guò)套餐配額增加緩存降低重復(fù)請(qǐng)求或者在網(wǎng)關(guān)層排隊(duì)削峰Decagon 沒(méi)有觸發(fā)搜索工具提示詞未配置或工具未啟用檢查工具是否上線改用明確的 prompt 描述觸發(fā)條件答案引用來(lái)源為空搜索服務(wù)未返回 citation 字段或字段映射錯(cuò)誤查看原始返回日志調(diào)整標(biāo)準(zhǔn)化函數(shù)中的字段映射生產(chǎn)環(huán)境搜索正常但客戶會(huì)話中報(bào)錯(cuò)會(huì)話上下文中的 query 過(guò)長(zhǎng)或工具參數(shù)解析失敗檢查 Decagon 工具參數(shù)模板限制 query 最大長(zhǎng)度搜索回答與知識(shí)庫(kù)沖突實(shí)時(shí)結(jié)果可信度不高或時(shí)效性標(biāo)記不明確在提示詞中要求“優(yōu)先實(shí)時(shí)結(jié)果并標(biāo)注來(lái)源”必要時(shí)人工抽樣檢查排查時(shí)建議按“日志 → 復(fù)現(xiàn) → 定位 → 修復(fù)”的順序推進(jìn)。第一步查看搜索網(wǎng)關(guān)日志確認(rèn)請(qǐng)求是否到達(dá)下游第二步用一個(gè)公開(kāi)測(cè)試接口復(fù)現(xiàn)問(wèn)題第三步對(duì)比成功和失敗的請(qǐng)求參數(shù)通常能很快定位到是鑒權(quán)、參數(shù)還是網(wǎng)絡(luò)問(wèn)題最后再修改代碼或配置并在測(cè)試環(huán)境回歸。8. 最佳實(shí)踐與工程建議8.1 外部服務(wù)依賴要“可替換”把 Perplexity 實(shí)時(shí)搜索服務(wù)封裝在統(tǒng)一接口后面是降低替換成本的關(guān)鍵。不要在主業(yè)務(wù)代碼中直接調(diào)用第三方 SDK 的類和方法而是先定義自己的 SearchPort 接口然后用 PerplexityAdapter 實(shí)現(xiàn)。這樣未來(lái)如果要換成其他搜索服務(wù)商只需要新增一個(gè) Adapter不用改動(dòng) Decagon 側(cè)的任何代碼。接口設(shè)計(jì)可以參考下面這個(gè)最小樣例。class SearchPort: def search(self, query: str) - Dict[str, Any]: raise NotImplementedError class PerplexityAdapter(SearchPort): def search(self, query: str) - Dict[str, Any]: raw search_real_time(query) return normalize_search_result(raw)這種設(shè)計(jì)也方便編寫(xiě)單元測(cè)試。測(cè)試一個(gè)搜索服務(wù)本身就是外部依賴如果直接打真實(shí)接口測(cè)試會(huì)慢且不穩(wěn)定。有了接口抽象我們可以用 Mock 對(duì)象模擬搜索結(jié)果快速驗(yàn)證 Decagon 側(cè)的業(yè)務(wù)邏輯。8.2 密鑰管理和敏感信息保護(hù)無(wú)論項(xiàng)目規(guī)模大小密鑰管理都要當(dāng)成最高優(yōu)先級(jí)。建議遵循最小權(quán)限原則只有搜索網(wǎng)關(guān)服務(wù)需要調(diào)用外部搜索其他服務(wù)一律不保存搜索 API Key。如果使用 Kubernetes把 Key 放在 Secret 中并配置 RBAC 權(quán)限只允許目標(biāo)服務(wù)讀取如果使用云服務(wù)器可以使用云廠商的密鑰管理服務(wù)。同時(shí)要定期輪換 API Key比如每 90 天輪換一次。輪換期間新舊 Key 可以并行存在一段時(shí)間避免更新配置瞬間服務(wù)不可用。這一條在對(duì)接大客戶時(shí)尤其重要因?yàn)榇罂蛻舻陌踩珗F(tuán)隊(duì)會(huì)定期檢查密鑰管理制度如果你能主動(dòng)展示輪換策略會(huì)更容易通過(guò)合規(guī)評(píng)審。8.3 成本控制與性能平衡實(shí)時(shí)搜索服務(wù)通常按調(diào)用量或 Token 計(jì)費(fèi)成本可能成為大客戶項(xiàng)目中的敏感話題?？刂瞥杀镜乃悸分饕兴膫€(gè)方向一是加緩存減少重復(fù)調(diào)用二是設(shè)置 query 復(fù)雜度限制避免無(wú)意義的長(zhǎng)查詢?nèi)窃跇I(yè)務(wù)層設(shè)計(jì)觸發(fā)條件只對(duì)確實(shí)需要最新信息的問(wèn)題調(diào)用搜索四是定期分析搜索日志把高頻且變化不大的問(wèn)題沉淀到知識(shí)庫(kù)逐步減少對(duì)外部搜索的依賴。性能方面除了在客戶端設(shè)置超時(shí)還要在網(wǎng)關(guān)層配置并發(fā)限制。服務(wù)商一般會(huì)有 QPS 上限超過(guò)后直接返回 429。如果我們內(nèi)部不限制并發(fā)而是讓所有請(qǐng)求同時(shí)涌向搜索服務(wù)很容易觸發(fā)限流。一個(gè)好的做法是在網(wǎng)關(guān)層引入信號(hào)量或令牌桶把最大并發(fā)控制在一個(gè)安全值例如 50超出的請(qǐng)求直接排隊(duì)或失敗降級(jí)。8.4 上線前的大客戶驗(yàn)收清單在正式交付給大客戶前建議對(duì)照以下清單做一輪內(nèi)部驗(yàn)收是否確認(rèn)了生產(chǎn)環(huán)境的 API Key 和網(wǎng)絡(luò)白名單是否完成了權(quán)限分離測(cè)試環(huán)境與生產(chǎn)環(huán)境使用不同 Key是否驗(yàn)證了搜索超時(shí)和搜索服務(wù)不可用時(shí)的降級(jí)鏈路是否配置了審計(jì)日志并能按租戶維度檢索是否設(shè)置了大客戶配額和異常告警是否在 Decagon 后臺(tái)完成了工具命名和提示詞模板的審核是否準(zhǔn)備了故障應(yīng)急預(yù)案明確負(fù)責(zé)人和回滾方式。這份清單并不復(fù)雜但很多團(tuán)隊(duì)在項(xiàng)目交付時(shí)因?yàn)榧庇谏暇€跳過(guò)了其中一兩項(xiàng)最后在客戶驗(yàn)收階段被反復(fù)打回。提前把驗(yàn)收標(biāo)準(zhǔn)確定好反而能加快整體交付速度。9. 總結(jié)與后續(xù)優(yōu)化方向至此我們完整梳理了 Decagon 接入 Perplexity 實(shí)時(shí)搜索服務(wù)服務(wù)大客戶的全過(guò)程從需求背景、方案設(shè)計(jì)到代碼實(shí)現(xiàn)、生產(chǎn)配置都給出了可落地的參考。核心思路可以概括為三點(diǎn)第一通過(guò)標(biāo)準(zhǔn)化客戶端封裝外部搜索服務(wù)降低替換成本第二通過(guò)工具調(diào)用和提示詞模板讓 Decagon 在合適的時(shí)機(jī)使用實(shí)時(shí)搜索第三通過(guò)多租戶隔離、緩存、限流、審計(jì)等工程手段滿足大客戶在安全、成本和可靠性方面的要求。如果你正在負(fù)責(zé)類似的實(shí)時(shí)搜索集成項(xiàng)目建議先不要急著寫(xiě)代碼而是和客戶確認(rèn)清楚幾個(gè)問(wèn)題實(shí)時(shí)搜索的使用場(chǎng)景是什么數(shù)據(jù)出域是否合規(guī)調(diào)用配額和預(yù)算上限是多少失敗的降級(jí)策略由誰(shuí)批準(zhǔn)。把這些問(wèn)題聊清楚后續(xù)開(kāi)發(fā)會(huì)順暢很多。實(shí)時(shí)搜索技術(shù)本身還在快速迭代接口參數(shù)和模型能力都會(huì)不斷變化但只要我們把架構(gòu)設(shè)計(jì)的足夠靈活保持對(duì)變化的適應(yīng)能力就能在大客戶服務(wù)中持續(xù)提供高質(zhì)量的支持。希望這篇實(shí)戰(zhàn)筆記能給正在做相關(guān)系統(tǒng)的你帶來(lái)一些可復(fù)用的思路。