我用Swagger/OpenAPI和大型语言模型函数调用规范做了定义

GitHub上的开源API项目页面: https://github.com/samchon/openapi

OpenAPI 和 LLM TypeScript 定義

@samchon/openapi 是一个包含各个版本 OpenAPI 类型及其转换器的集合。在这些 OpenAPI 类型中，该规范去除了含糊和重复的表达，从而使其更加清晰易懂。所有的转换均基于此修正后的 OpenAPI v3.1 规范。

1. Swagger v2.0
2. OpenAPI v3.0
3. OpenAPI v3.1
4. OpenAPI v3.1 更新版

@samchon/openapi 还提供了从 OpenAPI 文档生成调用大型语言模型（LLM）功能的应用程序合成器，提供了多种策略。通过 HttpLlm 模块，你可以极其方便地进行 LLM 功能调用，只需提供 OpenAPI（Swagger）文档即可。

• HttpLlm.application()
• IHttpLlmApplication<Model>
• IHttpLlmFunction<Model>

• 支持的模式有

• IChatGptSchema: OpenAI 的 ChatGPT

• IClaudeSchema: Anthropic 的 Claude

• IGeminiSchema: Google 的 Gemini

• ILlamaSchema: Meta 的 Llama

• 中间层模式包括

• ILlmSchemaV3: 基于 OpenAPI v3.0 规范的中间层

• ILlmSchemaV3_1: 基于 OpenAPI v3.1 规范的中间层

LLM 的函数调用 和 结构化的输出

LLM 选择合适的函数并填充参数。

目前，大多数像 OpenAI 这样的大型语言模型 (LLM) 都支持“函数调用”功能。“LLM 的函数调用”意味着 LLM 会根据与用户的对话（可能是聊天文本）自动选择合适的函数并填充参数值。

结构化的输出是 LLM 的另一个特性。“结构化的输出”指的是 LLM 会自动将对话输出转换为结构化数据格式，如 JSON。

• https://platform.openai.com/docs/guides/function-calling
• https://platform.openai.com/docs/guides/structured-outputs

@samchon/openapi 支持所有版本的 OpenAPI 规范，并提供详细的 TypeScript 类型定义。

• Swagger v2.0
• OpenAPI v3.0
• OpenAPI v3.1
• OpenAPI v3.1 修改版文档

此外，@samchon/openapi 提供了“更正后的 OpenAPI v3.1 定义”，去除了模糊和重复的表达，以提高清晰度。它对原始的 OpenAPI v3.1 规范进行了类似的更正。你可以通过调用 OpenApi.convert() 函数来生成“更正后的 OpenAPI v3.1 定义”。

• 操作

• 将 OpenApiV3_1.IPathItem.parameters 合并到 OpenApi.IOperation.parameters

• 解决引用 OpenApiV3_1.IOperation 成员的引用

• 转义引用 OpenApiV3_1.IComponents.examples 的引用

• JSON Schema

• 分解混合类型：OpenApiV3_1.IJsonSchema.IMixed

• 处理可空属性：OpenApiV3_1.IJsonSchema.__ISignificant.nullable

• 数组类型仅使用单个 OpenApi.IJsonSchema.IArray.items

• 元组类型仅使用前缀项：OpenApi.IJsonSchema.ITuple.prefixItems

• 将 OpenApiV3_1.IJsonSchema.IAnyOf 合并到 OpenApi.IJsonSchema.IOneOf

• 将 OpenApiV3_1.IJsonSchema.IRecursiveReference 合并到 OpenApi.IJsonSchema.IReference

• 将 OpenApiV3_1.IJsonSchema.IAllOf 合并到 OpenApi.IJsonSchema.IObject

转换到另一个版本的 OpenAPI 文档也是基于如图所示的“修订版 OpenAPI v3.1 规范”。你可以通过使用 OpenApi.downgrade() 函数来实现。因此，如果你想将 Swagger v2.0 文档转换为 OpenAPI v3.0 文档，你需要调用两个函数：先调用 OpenApi.convert()，再调用 OpenApi.downgrade()。

最后，，如果你使用 typia 库和 @samchon/openapi 类型，你可以验证你的 OpenAPI 文档是否符合标准规范。只需访问下面的任一在线验证工具链接，并粘贴你的 OpenAPI 文档的 URL 地址。这种验证策略会比任何其他 OpenAPI 验证库更加优越。

• Playground 链接页面

• 💻 类型确认

• 💻 详细检查

    import { OpenApi, OpenApiV3, OpenApiV3_1, SwaggerV2 } from "@samchon/openapi";
    import typia from "typia";

    const main = async (): Promise<void> => {
      // 获取你的 OPENAPI 文档如下
      const response: Response = await fetch(
        "https://raw.githubusercontent.com/samchon/openapi/master/examples/v3.0/openai.json"
      );
      const document: any = await response.json();

      // 进行类型验证
      const result = typia.validate<
        | OpenApiV3_1.IDocument
        | OpenApiV3.IDocument
        | SwaggerV2.IDocument
      >(document);
      if (result.success === false) {
        console.error(result.errors);
        return;
      }

      // 转换成 EMENDED 格式
      const emended: OpenApi.IDocument = OpenApi.convert(document);
      // 在控制台输出 emended
      console.info(emended);
    };
    main().catch(console.error);

全屏 退出全屏

调用LLM功能的应用，从开放API文档中获取信息。

@samchon/openapi 提供了一个调用大型语言模型 (LLM) 功能的工具，该工具基于改编的 OpenAPI v3.1 文档。因此，如果你有一个 HTTP 后端服务器和一个 OpenAPI 文档，你可以轻松地创建一个 AI 聊天机器人。

在AI聊天机器人中，LLM会从与用户的对话中选择合适的函数进行远程调用，并自动填充函数所需参数。如果你实际执行了HttpLlm.execute()函数来调用函数，这就是“LLM函数调用”。

下面是一个用 @samchon/openapi 调用 LLM 函数的示例代码。

• 示例代码: test/examples/chatgpt-function-call-to-sale-create.ts
• 描述要创建的产品的提示语: Microsoft Surface Pro 9
• 函数调用返回的结果: examples/arguments/chatgpt.microsoft-surface-pro-9.input.json

    import {
      HttpLlm,
      IChatGptSchema,
      IHttpLlmApplication,
      IHttpLlmFunction,
      OpenApi,
      OpenApiV3,
      OpenApiV3_1,
      SwaggerV2,
    } from "@samchon/openapi";
    import OpenAI from "openai";
    import typia from "typia";

    const main = async (): Promise<void> => {
      // 读取 Swagger 文档并验证它
      const swagger:
        | SwaggerV2.IDocument
        | OpenApiV3.IDocument
        | OpenApiV3_1.IDocument = JSON.parse(
        await fetch(
          "https://github.com/samchon/shopping-backend/blob/master/packages/api/swagger.json",
        ).then((r) => r.json()),
      );
      typia.assert(swagger); // 推荐的做法

      // 转换为扩展的 OpenAPI 文档，
      // 并组合 LLM 函数调用应用
      const document: OpenApi.IDocument = OpenApi.convert(swagger);
      const application: IHttpLlmApplication<"chatgpt"> = HttpLlm.application({
        model: "chatgpt",
        document,
      });

      // 假设 LLM 已经选择了一个需要调用的函数
      const func: IHttpLlmFunction<"chatgpt"> | undefined =
        application.functions.find(
          // (f) => f.name === "llm_selected_fuction_name"
          (f) => f.path === "/shoppings/sellers/sale" && f.method === "post",
        );
      if (func === undefined) throw new Error("没有找到匹配的函数。");

      // 通过 ChatGPT 调用获取函数参数
      const client: OpenAI = new OpenAI({
        apiKey: "<YOUR_OPENAI_API_KEY>",
      });
      const completion: OpenAI.ChatCompletion =
        await client.chat.completions.create({
          model: "gpt-4o",
          messages: [
            {
              role: "assistant",
              content:
                "您是一个乐于助人的客户支持助手，可以使用提供的工具来帮助用户。",
            },
            {
              role: "user",
              content: "<关于该销售的描述>",
              // https://github.com/samchon/openapi/blob/master/examples/function-calling/prompts/microsoft-surface-pro-9.md
            },
          ],
          tools: [
            {
              type: "function",
              function: {
                name: func.name,
                description: func.description,
                parameters: func.parameters as Record<string, any>,
              },
            },
          ],
        });
      const toolCall: OpenAI.ChatCompletionMessageToolCall =
        completion.choices[0].message.tool_calls![0];

      // 实际操作
      const article = await HttpLlm.execute({
        connection: {
          host: "http://localhost:37001",
        },
        application,
        function: func,
        input: JSON.parse(toolCall.function.arguments),
      });
      console.log("article", article);
    };
    main().catch(console.error);

全屏模式，退出全屏.

    import { ILlmApplication, ILlmFunction, ILlmSchema } from "@samchon/openapi";
    import typia from "typia";

    // 调用函数应用模式
    const app: ILlmApplication<"chatgpt"> = typia.llm.application<
      BbsArticleController,
      "chatgpt"
    >();
    const func: ILlmFunction<"chatgpt"> | undefined = app.functions.find(
      (f) => f.name === "create",
    );

    console.log(app);
    console.log(func);

    // 结构化输出结果
    const params: ILlmSchema.IParameters<"chatgpt"> = typia.llm.parameters<
      IBbsArticle.ICreate,
      "chatgpt"
    >();
    console.log(params);

进入全屏 退出全屏

💻 在线演练链接

仅仅通过 TypeScript 的类型。

你也可以从 TypeScript 类或接口类型来定义 LLM 函数调用的应用模式。同样，也可以从原生 TypeScript 类型来创建结构化输出格式。

接下来的文章中，我将教你如何使用typia的LLM函数调用模式编排器，并如何将其与AI聊天机器人进行集成。