ai-plugin.json 生成器
通过有效的清单文件，将您的API暴露给AI代理。
快速解答
ai-plugin.json 是一个清单文件，它将您的API作为可调用工具暴露给AI助手，托管在 /.well-known/ai-plugin.json 路径下。此生成器可根据您的名称、模型描述、身份验证类型和OpenAPI URL编写有效的清单文件，以便AI代理可以发现并调用您的端点。
交互式生成器本身为英文界面 — 本页面提供了您理解和使用它所需的一切说明。
将您的API暴露给AI代理
`ai-plugin.json` 清单文件是您的API与新兴AI助手生态系统之间的基本契约。它托管在可预测的 `/.well-known/ai-plugin.json` 路径下，不仅仅是元数据，更是一个关键的网关。我们的生成器确保您的清单文件严格遵循OpenAPI规范（OAS）引用，从而使GPT-4和Google Gemini等模型能够准确理解并调用您的函数。正确的生成对于无缝集成至关重要，它能有效避免 `invalid_manifest` 错误，确保可靠的工具调用。
精心制作关键的 `description_for_model`
`ai-plugin.json` 中的 `description_for_model` 字段可以说是对AI驱动工具使用影响最大的。这个简洁的字符串（通常少于200个字符）为大语言模型提供了提示工程上下文，使其能决定何时以及如何调用您的API。我们的生成器会指导您创建精确、面向动作的描述，例如“使用此插件检索给定股票代码的实时股价”，而不是模糊的通用描述。这种特异性将直接影响大语言模型调用您工具的倾向性。
身份验证与OpenAPI URL配置
安全地将您的API暴露给AI代理需要仔细的身份验证配置。`ai-plugin.json` 支持多种 `auth` 类型，包括 `none`、`oauth`（OAuth 2.0客户端凭证授权）和 `service_http`（Bearer令牌或基本身份验证）。我们的生成器有助于选择和配置这些类型，确保您的端点在受保护的同时可供授权代理访问。同时，它还会验证 `api.url` 条目，确认它指向一个实时、可发现的OpenAPI/Swagger规范（例如，`https://api.example.com/openapi.yaml`），这对于模型理解至关重要。
为何 `/.well-known/` 路径至关重要
`ai-plugin.json` 放置在 `/.well-known/` 路径并非随意而定；这是RFC 8615定义的用于主机元数据发现的标准。这个可预测的位置允许AI代理爬虫（如 `ChatGPT-User` 或 `Google-Extended`）无需明确配置即可高效发现和检索您的清单文件。这种标准化的发现机制最大程度地减少了代理的延迟和开销，使您的API能够立即被任何旨在在此指定且广泛采用的URI查找工具的AI系统使用。
常见的ai-plugin.json生成陷阱
| 问题 | 影响 | 缓解策略 | 爬虫响应 |
|---|---|---|---|
| JSON格式错误 | 清单解析失败，API无法被发现 | 使用linter或生成器进行严格的JSON验证 | 代理日志中出现 `HTTP 400 Bad Request` 或 `Invalid JSON` 错误。 |
| OpenAPI URL不正确 | API功能对大语言模型未知 | 验证 `api.url` 指向一个实时、有效的OpenAPI规范 | `API spec not found` 或 `Unparseable OpenAPI` 警告。 |
| 模糊的 `description_for_model` | 大语言模型利用不足 | 编写简洁、面向行动的描述（50-150字符） | 大语言模型未能选择工具，或错误解释意图。 |
| 缺少必填字段 | 清单被拒绝 | 确保 `name_for_model`、`name_for_human`、`description_for_model`、`api` 和 `auth` 存在 | `Missing required field` 或 `Manifest schema validation failed`。 |
| 没有 `/.well-known` 路径 | 清单无法被标准爬虫发现 | 严格将 `ai-plugin.json` 部署到 `/.well-known/ai-plugin.json` | 爬虫跳过主机，API对代理保持未知。 |
您的ai-plugin.json关键考量
- 确保 `name_for_model` 是一个简洁、唯一的标识符（例如，`stock_price_api`）。
- 验证 `description_for_model` 清晰、简洁且面向动作，以便大语言模型理解。
- 确认您的 `api.url` 指向一个公开可访问且有效的OpenAPI 3.0或3.1规范。
- 实施适当的 `auth` 配置（例如，`service_http` 用于Bearer令牌）。
- 将 `ai-plugin.json` 文件仅部署到 `/.well-known/ai-plugin.json` 路径。
- 审查 `legal_info_url` 和 `contact_email` 以确保合规性和支持。
- 定期使用工具验证生成的清单是否符合Schema。
- 在全面部署前，使用实际AI代理（例如ChatGPT Plugins）测试API调用。
部署AI插件清单的步骤
- 1定义核心API功能
清晰阐明您的API所支持的具体操作。确定关键的端点、参数和预期响应。这种清晰度将直接影响 `description_for_model` 和OpenAPI规范的编写。重点关注AI代理可以使用您的API“做什么”，而不仅仅是“它是什么”。
- 2生成OpenAPI规范
为您的API创建全面的OpenAPI（OAS 3.0/3.1）定义。此规范详细说明了所有端点、方法、参数和数据模型。确保其准确且最新，因为AI代理将解析此文档以理解您的API功能以及如何构建请求。
- 3配置清单详情
使用生成器输入您的 `name_for_model`、`description_for_model`、`auth` 类型（例如，`service_http` 用于API密钥）、`logo_url`、`legal_info_url` 和 `contact_email`。请密切关注 `description_for_model` 的编写，以优化大语言模型的理解和插件调用。
- 4验证生成的JSON
在部署之前，根据官方Schema仔细验证输出的 `ai-plugin.json`。检查语法错误、缺失字段和正确的URL格式。确保 `api.url` 精确指向您托管的OpenAPI规范，以防止 `ChatGPT-User` 等AI代理发现问题。
- 5将清单部署到 `/.well-known/`
将生成的 `ai-plugin.json` 文件托管到精确的URI `YOUR_DOMAIN/.well-known/ai-plugin.json`。这个标准路径对于AI代理爬虫自动发现您的插件至关重要，无需预先知识。放置不正确将导致您的插件无法被大多数AI系统发现。
- 6监控和迭代
部署后，监控您的API使用情况和代理交互日志。注意您的插件被调用的频率以及是否存在解析错误。利用这些反馈来完善您的 `description_for_model` 和OpenAPI规范，确保随着时间的推移，AI代理集成能够实现最佳性能和可靠性。
常见问题
- 什么是 `ai-plugin.json`，它对我的API为何重要？
- `ai-plugin.json` 是一个标准化的清单文件，它充当AI代理（如驱动ChatGPT或Gemini的代理）发现和理解您的API的蓝图。它至关重要，因为它使您的服务能够在AI生态系统中作为可调用工具存在，通过允许大语言模型代表用户以编程方式与您的API交互，显著扩展了您的API的覆盖范围和实用性。
- `ai-plugin.json` 文件必须确切地托管在哪里？
- `ai-plugin.json` 文件必须托管在相对于您的域名的 `/.well-known/ai-plugin.json` 路径下。例如，如果您的域名是 `example.com`，则该文件应通过 `https://example.com/.well-known/ai-plugin.json` 访问。这个标准化位置对于AI爬虫可靠地查找和索引您的插件清单至关重要。
- `description_for_model` 与 `description_for_human` 的目的是什么？
- `description_for_model` 提供一个简洁、面向动作的摘要，专门供大语言模型理解何时以及如何调用您的API（例如，“获取某个位置的当前天气数据”）。`description_for_human` 是一个用户友好的、更长的描述，显示给插件市场或目录中的人类用户。前者驱动AI调用，后者告知用户选择。
- `ai-plugin.json` 中支持哪些身份验证类型？
- `ai-plugin.json` 标准支持多种身份验证类型：`none` 用于无需身份验证的API，`oauth` 用于OAuth 2.0客户端凭证流程，以及 `service_http` 用于基于API密钥的身份验证（通过 `Authorization` 标头中的Bearer令牌或HTTP基本身份验证）。选择正确的类型对于向AI代理安全暴露API至关重要。
- 我可以使用自定义的OpenAPI规范URL作为我的API吗？
- 是的，`ai-plugin.json` 中的 `api.url` 字段应指向您的API的OpenAPI规范文档的直接URL（例如，`https://api.example.com/openapi.yaml` 或 `https://api.example.com/openapi.json`）。该URL必须可公开访问，并提供有效的OpenAPI 3.0或3.1规范，以便AI代理解析和理解您的API端点和Schema。
- 我应该多久更新一次 `ai-plugin.json`？
- 当您的API功能、身份验证方法或面向公众的描述发生重大变化时，您都应该更新 `ai-plugin.json`。即使 `description_for_model` 的微小更改也可能影响大语言模型的行为。目标是使其与API的当前状态保持同步，以确保AI代理始终拥有准确的信息。
- 如果我的 `ai-plugin.json` 格式错误或无效会发生什么？
- 如果您的 `ai-plugin.json` 格式错误、包含语法错误或缺少必填字段，AI代理很可能无法解析它。这将导致您的API无法被发现为工具，或者代理将报告 `invalid_manifest` 错误。使用验证器或像我们这样强大的生成器有助于防止这些关键的解析失败，并确保成功集成。
- 是否有特定的用户代理会抓取 `ai-plugin.json` 文件？
- 是的，各种AI代理平台使用特定的用户代理来发现和解析 `ai-plugin.json` 文件。值得注意的例子包括 `ChatGPT-User`（用于OpenAI的平台）和 `Google-Extended`（用于Google的AI服务）。确保您的 `robots.txt` 允许这些用户代理访问 `/.well-known/` 对于插件的成功发现和索引至关重要。