我构建了一个人工智能代理，让你用简单英语探索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检索账户详情？"，响应将包括账户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