我打造了一個 AI 代理，讓你能用白話文探索 API

我目前的產品有數百個 API。每次我需要參考 API 規格時，都必須導航到 Swagger 連結，無止境地滾動，或使用瀏覽器搜尋來找到我需要的內容—然後手動過濾掉不需要的東西。這既令人沮喪又痛苦地緩慢。更糟的是，每個需要與 API 整合的開發人員都必須經歷相同的體驗。

這種挫折感促使我探索 AI 如何改善這個流程。這篇文章深入探討了這段旅程，以及它如何演變成簡單、穩健且有效的解決方案。

準備工作

豐富的 API 文檔

作為第一步，我審查了整個 API 文檔，確保 Swagger 文檔中有清晰的摘要和描述細節。這對於後期更好的可發現性是關鍵步驟。我還確保每個 API 的摘要和描述都是獨特的。

paths": {     "/users/accounts/{account-id}": {       "put": {         "tags": [           "Account API"         ],         "summary": "Update Test suite by test-suite-id",         "externalDocs": {           "description": "Robust get account details description",           "url": "https://mydocs.com/description"         },

\

API 的分類

有數百個可用的 API，識別哪些是相關的可能具有挑戰性。對 API 進行分類使管理更有效率，並在後期簡化了基於自然語言輸入選擇正確 API 的過程。這種分類是使用 OpenAPI 規範中定義的標籤概念實現的。

\

"paths": {     "/users/accounts/{account-id}": {       "put": {         "tags": [           "Account API"         ],         "summary": "Update Test suite by test-suite-id",         "externalDocs": {           "description": "Robust get account details description",           "url": "https://mydocs.com/description"         },

\

建立自然語言搜尋

使用者輸入

使用者會輸入與 API 相關的自然語言問題。

例如：如何獲取帳戶詳細資訊？

分類類別

在這個階段，問題和所有可用的類別都會發送給 LLM。LLM 的任務是返回問題所屬的高級類別。這一步驟的輸出是其中一個類別。

分類特定 API

基於 LLM 識別的類別，系統會向模型發送另一個請求，包含相同的問題—但這次，它包括上一步驟中檢測到的特定類別內的所有 API 詳細資訊。

這就是前期準備工作發揮作用的地方：API 文檔越描述性和結構良好，結果就越好。清晰的描述幫助 LLM 準確確定使用者正在請求哪個 API 的資訊。

這一步驟的輸出是一個特定的 API。

豐富 API 回應詳細資訊

然後將 API 的 OpenAPI 規範提供給 LLM，以生成 API 的詳細、內容豐富的描述，同時包含原始問題。

例如，如果使用者問，"如何使用帳戶 ID 獲取帳戶詳細資訊？"，回應將包括 Account API 的相關規範詳細資訊。

擴展

隨著系統準確檢測適當 API 的能力增強，使用者現在可以更進一步—生成程式碼片段直接與各種 API 互動。

例如：

• "分享 Python 程式碼來呼叫獲取帳戶詳細資訊 API 以獲取特定 ID。"

• "提供 cURL 命令來通過 ID 獲取帳戶詳細資訊。"

• "生成 Go 客戶端來獲取特定 ID 的帳戶詳細資訊。"

\

經驗教訓和見解

• 豐富的文檔對於使用 AI 系統時獲得更好的準確性至關重要。精確、清晰且切中要點的文檔對於穩健性是必不可少的。額外收穫：我們還使用 LLM 為每個 API 生成摘要和描述，這極大地幫助了我們。
• 先進行分類
• 為什麼：有數百個 API，分類可以減少認知負擔並改善檢索。
• 如何：將相關 API 分組成一小組清晰的類別。當標籤空間有限時，AI 系統表現更好。
• 擴展提示：如果目錄非常大，添加子類別以進行更精細的路由。
• 迭代構建
• 從小開始：取規格的子集，訓練/驗證可靠選擇正確 API 的路由器。
• 逐步擴展：隨著時間增加更多 API，測量準確性，並優先處理分類錯誤的區域。
• 重點：在開始時優化精確度/召回率而非廣度。
• 與使用者閉環
• 收集反饋：捕捉系統選擇了錯誤 API 的案例。
• 根據信號行動：完善被誤識別 API 的描述、摘要和標籤；澄清重疊範圍。
• 重複：每次更改後重新評估，確認準確性有所提高並避免回歸。

結論

隨著可用 API 數量的持續增長，探索和管理它們需要一種新的方法。隨著由大型語言模型（LLM）驅動的 AI 代理的興起，開發人員現在有了一種更直觀、更高效的方式來發現和與 API 互動—節省了以前花在搜尋正確端點上的無數時間。

潛力不止於此。這個概念可以演變成一個獨立的產品，能夠在運行時無縫攝取 OpenAPI 規範，並通過自然語言界面公開它們—為使用者提供即用型的 API 探索解決方案。

希望這篇文章已經說明了如何有效利用 LLM，以及結構良好的 API 文檔如何創建更流暢、更智能的發現體驗。

\n \n

\n \n