还在手写JSON调教大模型？.NET 9有新玩法

引言

.NET 9 迎来了一项备受期待的功能更新：对JSON Schema的原生支持。这一新增功能极大地简化了JSON Schema的生成与使用。JSON Schema作为一种描述JSON数据结构的标准格式，能够帮助我们有效地验证数据结构和类型。尤其在与大语言模型（LLM）进行交互的场景中，它扮演着至关重要的角色，可以精确定义模型输入与输出的数据格式，从而确保通信的准确性和可靠性。

.NET 9 的新利器：JsonSchemaExporter

让我们从一个简单的例子开始。在.NET 9中，我们可以利用 System.Text.Json 命名空间下的新工具 JsonSchemaExporter，轻松地将一个C#类转换为对应的JSON Schema。

首先，我们定义一个名为 Book 的C#类。这个类包含三个属性：Title、Author 和 PublishYear。其中，Title 是一个必需的字符串属性，Author 是一个可空字符串属性，而 PublishYear 是一个整数。

// 定义一个名为 Book 的类
public class Book
{
    // 必须的字符串属性 Title
    public required string Title { get; set; }

    // 可选的字符串属性 Author，允许为 null
    public string? Author { get; set; }

    // 整数属性 PublishYear
    public int PublishYear { get; set; }
}

接下来，在主程序中，我们只需调用 JsonSchemaExporter.GetJsonSchemaAsNode 方法，并传入我们的 Book 类型，即可生成其JSON Schema。

class Program
{
    static void Main()
    {
        // 使用 JsonSchemaExporter 为 .NET 类型生成 JSON schema
        var schema = JsonSchemaExporter.GetJsonSchemaAsNode(
            JsonSerializerOptions.Default,
            typeof(Book)
        );

        // 输出生成的 JSON schema
        Console.WriteLine(schema);
    }
}

运行上述代码，我们将得到以下JSON Schema输出：

{
  "type": [
    "object",
    "null"
  ],
  "properties": {
    "Title": {
      "type": [
        "string",
        "null"
      ]
    },
    "Author": {
      "type": [
        "string",
        "null"
      ]
    },
    "PublishYear": {
      "type": "integer"
    }
  },
  "required": [
    "Title"
  ]
}

这个特性使得我们能够以标准化的JSON Schema形式来表示一个.NET类型，这对于实现远程过程调用（RPC）或与OpenAI、Google Gemini等AI服务进行集成时非常有用。

实战：结合OpenAI实现结构化输出

我们知道，从 gpt-4o-0806 开始，OpenAI便支持了通过JSON Schema来约束模型的输出格式。这个功能极大地便利了开发者，尤其是在需要模型返回复杂数据结构时。然而，手动编写和维护这些JSON Schema既繁琐又容易出错。现在，借助.NET 9的 JsonSchemaExporter，这个过程变得前所未有的简单。

注意：以下示例需要依赖 Azure.AI.OpenAI NuGet包 2.2.0 或更高版本。

让我们来看一个实际的例子。假设我们需要让大模型分析一段关于篮子里放球、取球的描述，并返回一个包含各种颜色球类数量的结构化数据。

首先，定义我们期望的输出数据结构 BallCounts 类：

public class BallCounts
{
    public string? Think { get; init; } // 模型的思考过程
    public int Red { get; init; }
    public int Blue { get; init; }
    public int Yellow { get; init; }
    public int Green { get; init; }
    public int Confidence { get; init; } // 模型对答案的置信度
}

然后，在调用模型时，我们可以将这个 BallCounts 类型动态生成JSON Schema，并直接传递给 ChatCompletionOptions 的 ResponseFormat。

// 初始化OpenAI客户端
OpenAIClient api = new AzureOpenAIClient(new Uri($"https://{Util.GetPassword("azure-ai-resource")}.openai.azure.com/"), new AzureKeyCredential(Util.GetPassword("azure-ai-key")));
ChatClient cc = api.GetChatClient("gpt-4o");

// 准备请求
var result = await cc.CompleteChatAsync(
    [
        new SystemChatMessage("你是人工智能助理"),
        new UserChatMessage("""
        有个空篮子，放里面放1个红色球，再往里面放1个蓝色球，再把红色球和黄色球拿出来，再放2个绿色球，请问这个篮子里面有几个球？分别是什么颜色？
        """),
    ],
    new ChatCompletionOptions()
    {
        Temperature = 0,
        // 关键点：动态生成并设置JSON Schema
        ResponseFormat = ChatResponseFormat.CreateJsonSchemaFormat(
            nameof(BallCounts),
            BinaryData.FromBytes(
                JsonSerializer.SerializeToUtf8Bytes(
                    JsonSchemaExporter.GetJsonSchemaAsNode(
                        JsonSerializerOptions.Default,
                        typeof(BallCounts),
                        new JsonSchemaExporterOptions()
                        {
                            // 确保非可空引用类型不被视为可空
                            TreatNullObliviousAsNonNullable = true
                        }
                    )
                )
            )
        )
    });

// 反序列化并输出结果
var ballCountsResult = JsonSerializer.Deserialize<BallCounts>(result.Value.Content[0].Text, JsonSerializerOptions.Default);
Console.WriteLine(JsonSerializer.Serialize(ballCountsResult, new JsonSerializerOptions { WriteIndented = true }));

模型返回的将是严格符合我们C#类结构的JSON：

{
  "Think": "Let's break down the steps:\n\n1. Start with an empty basket.\n2. Add 1 red ball. (Basket: 1 red)\n3. Add 1 blue ball. (Basket: 1 red, 1 blue)\n4. Remove the red ball. (Basket: 1 blue)\n5. Remove the yellow ball. (Since there is no yellow ball in the basket, this step doesn't change anything. Basket: 1 blue)\n6. Add 2 green balls. (Basket: 1 blue, 2 green)\n\nSo, the basket contains 3 balls: 1 blue and 2 green.",
  "Red": 0,
  "Blue": 1,
  "Yellow": 0,
  "Green": 2,
  "Confidence": 100
}

随心所欲，轻松扩展

这个方法的强大之处在于其灵活性。如果我们想调整输出结构，比如增加两种颜色（紫色和橙色），并将 Confidence 属性改为布尔类型的 Sure，我们 只需要修改C#类定义 即可。

public class BallCounts
{
    public string? Think { get; init; }
    public int Red { get; init; }
    public int Blue { get; init; }
    public int Yellow { get; init; }
    public int Green { get; init; }
    public int Purple { get; init; } // 新增
    public int Orange { get; init; } // 新增
    public bool Sure { get; init; }   // 修改
}

我们无需改动任何调用逻辑，只需重新运行程序，模型就会自动适应新的 BallCounts 结构，输出的JSON会神奇地包含所有新的颜色属性，并且 Sure 属性也被正确地处理为布尔值。

{
  "Think": "Let's break down the steps:\n\n1. Start with an empty basket.\n2. Add 1 red ball.\n3. Add 1 blue ball.\n4. Remove the red ball.\n5. Remove the yellow ball (though there was no yellow ball added, so this step doesn't change the count).\n6. Add 2 green balls.\n\nAfter these steps, the basket contains:\n- 1 blue ball\n- 2 green balls\n\nTotal: 3 balls.",
  "Red": 0,
  "Blue": 1,
  "Yellow": 0,
  "Green": 2,
  "Purple": 0,
  "Orange": 0,
  "Sure": true
}

可见，模型完美地适应了新的数据契约。这种开发体验简直不要太方便！

对比：新方法 vs. 传统方法

有趣的是，在OpenAI官方的.NET SDK文档中，关于结构化响应的示例 (openai-dotnet/README.md) 并没有采用 JsonSchemaExporter，而是手动编写了一大段JSON Schema字符串。这可能是因为官方文档旨在展示其库的原始能力，而非特定于.NET 9的便捷特性。

这是官网的示例代码，我们可以看到它相当繁琐：

// ...
ChatCompletionOptions options = new()
{
    ResponseFormat = ChatResponseFormat.CreateJsonSchemaFormat(
        jsonSchemaFormatName: "math_reasoning",
        jsonSchema: BinaryData.FromBytes("""
            {
                "type": "object",
                "properties": {
                    "steps": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "explanation": { "type": "string" },
                                "output": { "type": "string" }
                            },
                            "required": ["explanation", "output"],
                            "additionalProperties": false
                        }
                    },
                    "final_answer": { "type": "string" }
                },
                "required": ["steps", "final_answer"],
                "additionalProperties": false
            }
            """u8.ToArray()),
        jsonSchemaIsStrict: true)
};
// ...

与我们前面的方法相比，这种硬编码Schema的方式不仅工作量大，而且在需求变更时极难维护。而.NET 9的 JsonSchemaExporter 真正实现了“定义一次，处处使用”的优雅编程范式。

值得一提的是，据我了解，Google Gemini、Ollama等其他主流模型服务提供商也已支持JSON Schema格式化。这意味着您学到的这项技巧具有广泛的适用性。

总结

.NET 9中引入的 JsonSchemaExporter 无疑是.NET开发者与大语言模型协作时的一大福音。它将繁琐、易错的JSON Schema手动编写过程，转变为基于C#类型定义的自动化、强类型、可维护的流程。

这项功能特别好，它是将基于概率、本质不稳定的语言模型进行工程化，提升其输出结果稳定性和可靠性的关键手段。强烈建议您在自己的项目中，尤其是在与大模型交互时，全面拥抱JSON Schema来定义数据契约。借助.NET 9，我们现在可以无比轻松地生成和使用JSON Schema，从而显著提高代码的可读性、可维护性和整体开发效率。

---

感谢阅读，欢迎评论点赞！

欢迎加入「.NET骚操作」技术交流群：495782587