LangChain Go 结构化 JSON 输出实战基于 OpenAI json_schema 的 Structured Output 完整指南【免费下载链接】langchaingoLangChain for Go, the easiest way to write LLM-based programs in Go项目地址: https://gitcode.com/GitHub_Trending/la/langchaingo本篇技术指南以 examples/openai-jsonformat-example 为例系统讲解如何使用 LangChain Gogithub.com/tmc/langchaingo对接 OpenAI GPT-4o通过response_format: json_schema让模型严格输出符合 JSON Schema 定义的结构化 JSON并深入剖析底层实现原理与两种 JSON 模式的取舍。读完本文你将掌握结构化输出Structured Output的完整链路从 Schema 定义、客户端配置、请求发送到结果解析可直接迁移到数据抽取、表单生成、API 结果规整等真实场景。示例概览这个程序做了什么官方示例 README.md 将整个程序概括为两个核心步骤我们逐一展开建立与 OpenAI API 的连接使用 GPT-4o 模型并通过WithResponseFormat在客户端级别声明结构化 JSON 输出格式向模型发起提示Prompt要求其将非结构化文本转换为预定义结构的 JSON 输出。示例场景非常典型System 消息声明你是结构化数据抽取专家Human 消息给出自然语言问题please tell me the most famous people in history模型最终返回一个符合{name, age, role}结构的 JSON 对象。这正是非结构化输入 → 结构化输出这一工业级需求的最小可运行范例。环境准备与运行步骤按 README.md 的说明运行前需要满足三个条件安装 Go示例模块在 go.mod 中声明go 1.24.3本地 Go 版本需不低于该版本示例依赖github.com/tmc/langchaingo v0.1.14-pre.4以及tiktoken-go、regexp2、google/uuid等间接依赖。配置 OpenAI API Key 环境变量LangChain Go 的 OpenAI 客户端默认从OPENAI_API_KEY环境变量读取令牌见 openaillm_option.go。同样地模型名默认读取OPENAI_MODELBase URL 默认读取OPENAI_BASE_URL未设置时回落到https://api.openai.com/v1。运行程序# 进入示例目录后执行 go run openai_jsonformat.go运行成功后程序会将模型返回的 JSON 字符串打印到控制台示例中使用log.Fatal(completion.Choices[0].Content)输出结果。如果你使用OPENAI_BASE_URL或OPENAI_API_BASE指向兼容 OpenAI 协议的网关如本地代理同样适用于本示例。核心实现全解析示例核心代码位于 openai-jsonformat.go整体分为四个环节。第一步定义目标输出结构程序先定义一个 Go 结构体User用于表达期望的输出形状type User struct { Name string json:name Age int json:age }这里结构体主要起文档化作用——真正约束模型的是下面构造的 JSON Schema。第二步构造 JSON Schema 响应格式这是结构化输出的关键。示例通过openai.ResponseFormat声明json_schema类型并内嵌一份完整的 JSON Schemafomat : openai.ResponseFormat{ Type: json_schema, JSONSchema: openai.ResponseFormatJSONSchema{ Name: object, Schema: openai.ResponseFormatJSONSchemaProperty{ Type: object, Properties: map[string]*openai.ResponseFormatJSONSchemaProperty{ name: { Type: string, Description: The name of the user, }, age: { Type: integer, Description: The age of the user, }, role: { Type: string, Description: The role of the user, }, }, AdditionalProperties: false, Required: []string{name, age, role}, }, Strict: true, }, }这段配置对应 OpenAI Structured Output 的response_format.json_schema参数Type: json_schema开启严格模式Strict: true要求模型输出必须完全匹配 Schema注意Required与AdditionalProperties: false是 strict 模式的强制要求AdditionalProperties: false禁止输出 Schema 之外的字段Required列出必填字段。可以看到示例的Properties中比User结构体多了一个role字段——JSON Schema 与 Go 结构体是两套独立定义Schema 才是真正决定输出的依据。第三步创建带响应格式的客户端llm, err : openai.New(openai.WithModel(gpt-4o), openai.WithResponseFormat(fomat)) if err ! nil { log.Fatal(err) }WithResponseFormat是客户端级 Option定义于 openaillm_option.go将响应格式固化在客户端实例上之后每次GenerateContent调用都会携带该格式WithModel(gpt-4o)显式指定模型当前仓库默认模型为gpt-3.5-turbo见 chat.go。第四步构造消息并发起生成content : []llms.MessageContent{ llms.TextParts(llms.ChatMessageTypeSystem, You are an expert at structured data extraction. You will be given unstructured text from a research paper and should convert it into the given structure.), llms.TextParts(llms.ChatMessageTypeHuman, please tell me the most famous people in history), } completion, err : llm.GenerateContent(ctx, content, llms.WithJSONMode()) if err ! nil { log.Fatal(err) } log.Fatal(completion.Choices[0].Content)请求通过llms.MessageContent构造多段消息System HumanGenerateContent返回llms.ContentResponseChoices[0].Content即为模型生成的 JSON 字符串。值得注意示例同时使用了WithJSONMode()与客户端级WithResponseFormat二者并不冲突实际请求以客户端级格式为准见下文原理分析。源码级原理JSON 格式如何穿透到 HTTP 请求理解结构化输出的底层链路需要把三层代码串起来看。第一层调用级 Option。options.go 定义了WithJSONMode()它只是把CallOptions.JSONMode置为true属于请求级开关。第二层请求装配。在 openaillm.go 的请求构造逻辑中装配顺序清晰地体现了优先级if opts.JSONMode { req.ResponseFormat ResponseFormatJSON } ... // if o.client.ResponseFormat is set, use it for the request if o.client.ResponseFormat ! nil { req.ResponseFormat o.client.ResponseFormat }也就是说WithJSONMode()会先注入一个预置的json_object格式若客户端通过WithResponseFormat设置了自定义格式则后者覆盖前者。这正是示例同时写两种配置也不会出错的原因。ResponseFormatJSON是包级预置变量定义于 openaillm_option.goResponseFormat{Type: json_object}。第三层HTTP 序列化。最终ResponseFormat被写入 chat.go 中ChatRequest.ResponseFormat字段并以response_format的 JSON key 发送到/chat/completions接口见 chat.go。请求构造还包含一段细节MarshalJSON会确保max_tokens与max_completion_tokens不同时出现并针对 o1/o3/GPT-5 等推理模型自动省略temperature字段chat.go——这些是 OpenAI 兼容接口的隐含约束。两种 JSON 模式对比json_object 与 json_schemaLangChain Go 提供两种 JSON 约束模式适用场景截然不同维度json_objectWithJSONModejson_schemaStructured Output启用方式调用GenerateContent(..., llms.WithJSONMode())客户端WithResponseFormat构造json_schema格式底层参数response_format: {type: json_object}response_format: {type: json_schema, json_schema: {...}}约束强度仅保证输出是合法 JSON不校验字段结构与类型按 Schema 严格校验字段、类型、必填项Strict: true时强制匹配适用场景只需 JSON 外壳、字段灵活的通用场景数据抽取、表单规整、需要稳定字段契约的场景前提条件提示中需包含json字样引导模型RequiredAdditionalProperties: false为 strict 模式硬性要求从源码看两种模式最终都会写入同一个req.ResponseFormat字段openaillm.go区别只在于Type与JSONSchema是否携带——这也解释了为什么客户端级json_schema会覆盖请求级的json_object。JSON Schema 属性详解chat.go 中定义了三个与结构化输出直接相关的类型字段含义如下ResponseFormatJSONSchemaPropertySchema 节点支持递归嵌套字段JSON 字段说明Typetype类型如object、string、integer、array、number、booleanDescriptiondescription字段语义说明帮助模型正确填充可选Enumenum允许取值的白名单可选Itemsitems数组元素 SchemaType为array时必填Propertiesproperties对象的子属性映射Type为object时使用AdditionalPropertiesadditionalProperties是否允许额外字段strict 模式必须为falseRequiredrequired必填字段列表Ref$ref引用其他 Schema 定义可选ResponseFormatJSONSchema包含NameSchema 名称、Strict是否启用严格校验、Schema根 Schema 节点三个字段。ResponseFormat最外层结构Type取json_schema时携带JSONSchema。测试验证从示例到官方单测结构化输出并非孤例仓库的单元测试 structured_output_test.go 给出了与示例同构但更丰富的验证用例可作为扩展参考TestStructuredOutputObjectSchema定义math_schemafinal_answer字段验证模型输出包含final_answer键——与示例同样使用Strict: trueAdditionalProperties: falseRequired的固定套路TestStructuredOutputObjectAndArraySchema展示Type: array与Items的组合说明 Schema 支持嵌套数组结构steps: string[]TestStructuredOutputFunctionCalling不依赖json_schema而是通过llms.WithTools传入带Strict: true的 Function Definition验证工具调用的参数同样以严格 JSON 形式返回——这是结构化输出的另一条等价路径。这些测试与示例共同印证LangChain Go 的 OpenAI 客户端对 Structured Output 的支持覆盖了普通对话 响应格式与工具调用 严格参数两条主流形态。实战扩展建议与注意事项解析返回值completion.Choices[0].Content返回的是 JSON 字符串可用标准库encoding/json反序列化到你的 Go 结构体如示例中的User或直接用json.RawMessage保留原始结构。Schema 与结构体保持一致示例中User与 Schema 的role字段不一致实际项目建议由同一份定义生成或保持同步避免Schema 约束了输出、结构体却解析不了的错位。strict 模式的硬性约束Strict: true时Schema 必须满足 OpenAI 的限制所有属性进required、additionalProperties为false、不支持部分关键字否则 API 会直接报错。客户端级 vs 请求级同一客户端需要多种格式时优先使用请求级WithJSONMode()/工具调用方式格式固定时使用客户端级WithResponseFormat更简洁注意它会覆盖每次调用的格式。模型兼容性严格 JSON Schema 输出对模型版本有要求示例与测试均使用 GPT-4o 系列如gpt-4o、gpt-4o-2024-08-06旧版模型建议先用json_object模式验证可行性。通过本指南你已经掌握 LangChain Go 结构化 JSON 输出的完整技术栈从 示例程序 的实战写法到 chat.go 的 Schema 类型体系再到 openaillm.go 的格式装配优先级。下一步可以直接将这套模式套用到你自己的数据抽取或表单生成任务中。【免费下载链接】langchaingoLangChain for Go, the easiest way to write LLM-based programs in Go项目地址: https://gitcode.com/GitHub_Trending/la/langchaingo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考