尧图网页设计 
使用 instructor 在 OpenAI Chat Completions 中实现音频结构化输出gpt-4o-audio-preview【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor本文面向希望通过 OpenAI 音频模型从语音/音频中提取结构化数据的开发者。围绕docs/blog/posts/openai-multimodal.md的核心讲解结合 instructor 仓库中 instructor/v2/core/multimodal.py 与 instructor/v2/providers/openai/multimodal.py 的源码实现带你掌握gpt-4o-audio-preview在 Chat Completions API 下的音频输入、工具调用与Audio多模态辅助类的完整用法。读完你将能直接把一段本地 WAV/MP3 转成 Pydantic 结构化结果并清楚知道音频格式校验、modalities与audio参数的真实作用。背景Chat Completions API 的音频支持OpenAI 在 Chat Completions API 中引入了音频能力核心载体是gpt-4o-audio-preview模型。它让开发者沿用熟悉的 Chat Completions 接口就能完成输入音频 → 输出文本/结构化数据的交互为音频与文本结合的各类应用打开了新空间。从 instructor 的视角看这条能力被封装进了统一的Audio多模态辅助类。无论是 URL、Google Cloud StorageGCSURL、本地文件路径还是 base64 字符串你都可以用同一套 API 加载音频再由 instructor 在幕后完成 provider 相关的格式转换。相关的完整多模态指南见 docs/concepts/multimodal.mdOpenAI 整体接入指南见 docs/integrations/openai.md。关键特性灵活输入API 可处理任意文本与音频的组合输入消息内容可以同时包含文字指令和音频片段。自然、可控制的语音输出与 Realtime API 类似可以通过 prompt 塑造生成音频的语言、发音、情感范围等属性当modalities包含audio时。工具调用集成音频支持与既有工具调用function/tool calling无缝衔接可实现音频、文本与外部工具组合的复杂工作流——instructor 的response_model正是通过工具调用机制实现结构化输出的。快速上手从音频中提取结构化信息最直接的应用是从音频文件里提取结构化数据。下面这个例子在 examples/openai-audio/run.py 中有完整可运行版本from pydantic import BaseModel import instructor from instructor.processing.multimodal import Audio client instructor.from_provider(openai/gpt-5-nano) class Person(BaseModel): name: str age: int resp client.create( modelgpt-4o-audio-preview, response_modelPerson, modalities[text], audio{voice: alloy, format: wav}, messages[ { role: user, content: [ Extract the following information from the audio, Audio.from_path(./output.wav), ], }, ], ) print(resp) # Expected output: Person(nameJason, age20)流程拆解Audio.from_path(./output.wav)读取本地文件并自动转为 base64 编码放入请求实现见 instructor/v2/core/multimodal.py 中Audio.from_path文件不存在会抛FileNotFoundError空文件抛ValueErrormodalities[text]表示本次只要求文本输出即response_model的结构化字段audio{voice: alloy, format: wav}声明与音频相关的配置当不需要模型生成音频时该参数主要用于声明输入音频的格式信息response_modelPerson由 instructor 注入到工具调用流程中最终把模型的输出解析、校验成 Pydantic 对象。在 examples/openai-audio/run.py 中官方示例还展示了另一种等价写法——先用instructor.from_openai(OpenAI())包装客户端然后手动把文件 base64 编码后交给Audio.from_path核心调用参数与上面完全一致from openai import OpenAI from pydantic import BaseModel import instructor from instructor.processing.multimodal import Audio import base64 client instructor.from_openai(OpenAI()) class Person(BaseModel): name: str age: int with open(./output.wav, rb) as f: encoded_string base64.b64encode(f.read()).decode(utf-8) resp client.chat.completions.create( modelgpt-4o-audio-preview, response_modelPerson, modalities[text], audio{voice: alloy, format: wav}, messages[ { role: user, content: [ Extract the following information from the audio, Audio.from_path(./output.wav), ], }, ], ) # type: ignore print(resp) # Person(nameJason, age20)两种方式下instructor 都会把消息内容中的Audio对象转换为 OpenAI 期望的input_audio结构。Audio 辅助类的完整方法矩阵Audio与图片的Image、PDF 的PDF一样是 instructor 多模态统一接口的一部分。在 docs/concepts/multimodal.md 中给出了完整的支持矩阵MethodOpenAIGoogle GenAIfrom_url()✅✅from_gs_url()✅✅from_path()✅✅from_base64()✅✅autodetect()✅✅注意目前仅 OpenAI 与 Gemini 支持音频输入对 Geminiinstructor 默认以原始 bytes 传入也可改用 Files API详见 docs/integrations/genai.md。各方法的行为在 instructor/v2/core/multimodal.py 中均有实现from_path(path)校验文件存在且非空通过mimetypes.guess_type推断 MIME 类型audio/x-wav会归一化为audio/wavWindows 下的audio/vnd.dlna.adts会归一化为audio/aac随后读取文件字节并 base64 编码类型不在VALID_AUDIO_MIME_TYPES列表aac/flac/mp3/m4a/mpeg/mpga/mp4/opus/pcm/wav/webm中会抛ValueError。from_url(url)内部调用fetch_remote_content拉取远端内容按MAX_AUDIO_BYTES限制大小相关常量定义于 instructor/v2/core/remote.py校验Content-Type后 base64 编码。from_gs_url(gs_url)把gs://转换为https://storage.googleapis.com/...公共 URL 后再抓取因此要求对象必须公开可读默认超时 30 秒。from_base64(data_uri)解析data:audio/...;base64,前缀并校验媒体类型。autodetect(source)自动判断输入是 base64、HTTP(S) URL、GCS URL 还是本地路径分派给对应方法。关于autodetect_imagesTrueinstructor 还提供了autodetect_imagesTrue参数把 URL、GCS URL、本地路径等作为普通字符串放入消息内容时系统会自动检测并转换为对应的Image/Audio/PDF对象核心逻辑为 instructor/v2/core/multimodal.py 中的autodetect_media与convert_messages。不过对音频输入推荐显式使用Audio.from_*更利于校验与可读性。输入格式约束OpenAI 只接受 WAV 或 MP3这是最容易踩坑的一点。在 instructor/v2/providers/openai/multimodal.py 的audio_to_openai中只有audio/mp3、audio/mpeg、audio/mpga统一映射为mp3与audio/wav、audio/x-wav统一映射为wav被接受其他格式例如audio/aac会直接抛出ValueError而不是发送标签错误的字节给 API 解码失败。对应的测试用例见 tests/v2/test_core_multimodal_runtime.pydef test_audio_to_openai_format_follows_media_type() - None: from instructor.v2.providers.openai.multimodal import audio_to_openai mp3 Audio(sourceclip.mp3, media_typeaudio/mpeg, dataZmFrZQ) assert audio_to_openai(mp3, Mode.TOOLS)[input_audio][format] mp3 wav Audio(sourceclip.wav, media_typeaudio/wav, dataZmFrZQ) assert audio_to_openai(wav, Mode.TOOLS)[input_audio][format] wav aac Audio(sourceclip.aac, media_typeaudio/aac, dataZmFrZQ) with pytest.raises(ValueError, matchExpected WAV or MP3): audio_to_openai(aac, Mode.TOOLS)Audio对象最终会转换为如下 OpenAI 消息内容块类型为input_audio{ type: input_audio, input_audio: { data: base64-encoded audio bytes, format: wav } }基于 URL 与 GCS 的音频提取示例音频不一定来自本地文件。下面是 docs/concepts/multimodal.md 中给出的两种来源的完整示例示例音频为仓库测试资源tests/assets/gettysburg.wav对应的公开地址即盖茨堡演讲录音from pydantic import BaseModel import instructor from instructor.processing.multimodal import Audio # Initialize the client client instructor.from_provider(openai/gpt-4o-audio-preview) # Define our response model class AudioDescription(BaseModel): summary: str transcript: str url https://raw.githubusercontent.com/instructor-ai/instructor/main/tests/assets/gettysburg.wav # Make the API call with the audio file resp client.create( response_modelAudioDescription, modalities[text], audio{voice: alloy, format: wav}, messages[ { role: user, content: [ Extract the following information from the audio:, Audio.from_url(url), ], }, ], ) print(resp) summaryThis excerpt is from a famous historical speech discussing the founding principles of equality and liberty, and the ongoing civil war testing the endurance of those principles. transcriptFour score and seven years ago our fathers brought forth on this continent a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal. Now we are engaged in a great civil war, testing whether that nation, or any nation so conceived and so dedicated, can long endure. GCS 版本只是把来源换成Audio.from_gs_url(gs://my-bucket/path/to/audio.wav)其余参数完全一致gs_url gs://my-bucket/path/to/audio.wav resp client.create( response_modelAudioDescription, modalities[text], audio{voice: alloy, format: wav}, messages[ { role: user, content: [ Extract the following information from the audio:, Audio.from_gs_url(gs_url), ], }, ], )注意 GCS 对象必须公开可读否则from_gs_url会抛出ValueError(Failed to access GCS audio (must be publicly readable))。从音频提取扩展到通用多模态虽然本篇文章聚焦音频但理解 instructor 的Audio在消息内容中的位置有助于你在更复杂的场景中组合使用。instructor 把Image、Audio、PDF统一为多模态内容对象消息的content可以是文本 多模态对象的列表。以 docs/concepts/multimodal.md 中 PDF 发票解析为例import instructor from pydantic import BaseModel from instructor.processing.multimodal import PDF # Set up the client url https://raw.githubusercontent.com/instructor-ai/instructor/main/tests/assets/invoice.pdf client instructor.from_provider(openai/gpt-4.1-mini) # Create a model for analyzing PDFs class Invoice(BaseModel): total: float items: list[str] # Load and analyze a PDF response client.create( response_modelInvoice, messages[ { role: user, content: [ Analyze this document, PDF.from_url(url), ], } ], ) print(response) total220.0 items[English Tea - 2 units at $100 each, Tofu - 10 units at $2 each] 这说明一条消息里混排文本 多种媒体是统一设计convert_contents会根据当前模式把Audio/Image/PDF分派到对应 provider 的编码器。可进一步参考 tests/multimodal/test_multimodal.py 与 tests/v2/test_core_multimodal_runtime.py 中的运行时验证。使用场景语音助手构建更自然、更具上下文感知能力的语音交互界面把用户语音直接解析为意图/实体结构化数据。音频内容分析从录音、播客中自动提取信息、要点或情绪例如上面的AudioDescriptionsummary transcript。语言学习工具开发能听懂并回应口语的交互式语言学习应用语音识别 结构化反馈。无障碍功能通过音频交互与文本转语音能力改善应用可访问性把语音输入 → 结构化结果作为无障碍链路的一环。注意事项与限制延迟定位该功能最适合对极低延迟要求不高的异步场景需要动态、实时交互时OpenAI 官方推荐使用 Realtime API。格式限制OpenAI Chat Completions 音频输入仅接受 WAV / MP3务必在上游先把音频转成这两种格式之一。Responses API 不支持音频从 instructor/v2/providers/openai/multimodal.py 可以看到audio_to_openai在RESPONSES_TOOLS模式下会直接抛ValueError(OpenAI Responses doesnt support audio)音频结构化输出应使用 Chat Completions 相关模式。模型可用性示例中的gpt-4o-audio-preview为 OpenAI 的预览模型实际接入前请确认你的账号可用模型列表与当前模型 ID模型选择参考 docs/integrations/model-selection.mdinstructor.from_provider的第一个参数传入的是结构化输出所用的模型二者可以不同但请按你的实际账号配置调整。伦理与偏差与所有 AI 功能一样需评估音频处理与生成中的伦理问题与潜在偏差在真实用户群体上充分测试。相关文档Multimodal Guide —— 多模态Image / Audio / PDF综合参考OpenAI Integration —— OpenAI 完整接入指南Gemini Multimodal —— 另一套多模态实现Prompt Caching —— 大音频文件的缓存处理Monitoring with Logfire —— 跟踪多模态处理过程【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 instructor 在 OpenAI Chat Completions 中实现音频结构化输出（gpt-4o-audio-preview）
使用 instructor 在 OpenAI Chat Completions 中实现音频结构化输出gpt-4o-audio-preview【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor本文面向希望通过 OpenAI 音频模型从语音/音频中提取结构化数据的开发者。围绕docs/blog/posts/openai-multimodal.md的核心讲解结合 instructor 仓库中 instructor/v2/core/multimodal.py 与 instructor/v2/providers/openai/multimodal.py 的源码实现带你掌握gpt-4o-audio-preview在 Chat Completions API 下的音频输入、工具调用与Audio多模态辅助类的完整用法。读完你将能直接把一段本地 WAV/MP3 转成 Pydantic 结构化结果并清楚知道音频格式校验、modalities与audio参数的真实作用。背景Chat Completions API 的音频支持OpenAI 在 Chat Completions API 中引入了音频能力核心载体是gpt-4o-audio-preview模型。它让开发者沿用熟悉的 Chat Completions 接口就能完成输入音频 → 输出文本/结构化数据的交互为音频与文本结合的各类应用打开了新空间。从 instructor 的视角看这条能力被封装进了统一的Audio多模态辅助类。无论是 URL、Google Cloud StorageGCSURL、本地文件路径还是 base64 字符串你都可以用同一套 API 加载音频再由 instructor 在幕后完成 provider 相关的格式转换。相关的完整多模态指南见 docs/concepts/multimodal.mdOpenAI 整体接入指南见 docs/integrations/openai.md。关键特性灵活输入API 可处理任意文本与音频的组合输入消息内容可以同时包含文字指令和音频片段。自然、可控制的语音输出与 Realtime API 类似可以通过 prompt 塑造生成音频的语言、发音、情感范围等属性当modalities包含audio时。工具调用集成音频支持与既有工具调用function/tool calling无缝衔接可实现音频、文本与外部工具组合的复杂工作流——instructor 的response_model正是通过工具调用机制实现结构化输出的。快速上手从音频中提取结构化信息最直接的应用是从音频文件里提取结构化数据。下面这个例子在 examples/openai-audio/run.py 中有完整可运行版本from pydantic import BaseModel import instructor from instructor.processing.multimodal import Audio client instructor.from_provider(openai/gpt-5-nano) class Person(BaseModel): name: str age: int resp client.create( modelgpt-4o-audio-preview, response_modelPerson, modalities[text], audio{voice: alloy, format: wav}, messages[ { role: user, content: [ Extract the following information from the audio, Audio.from_path(./output.wav), ], }, ], ) print(resp) # Expected output: Person(nameJason, age20)流程拆解Audio.from_path(./output.wav)读取本地文件并自动转为 base64 编码放入请求实现见 instructor/v2/core/multimodal.py 中Audio.from_path文件不存在会抛FileNotFoundError空文件抛ValueErrormodalities[text]表示本次只要求文本输出即response_model的结构化字段audio{voice: alloy, format: wav}声明与音频相关的配置当不需要模型生成音频时该参数主要用于声明输入音频的格式信息response_modelPerson由 instructor 注入到工具调用流程中最终把模型的输出解析、校验成 Pydantic 对象。在 examples/openai-audio/run.py 中官方示例还展示了另一种等价写法——先用instructor.from_openai(OpenAI())包装客户端然后手动把文件 base64 编码后交给Audio.from_path核心调用参数与上面完全一致from openai import OpenAI from pydantic import BaseModel import instructor from instructor.processing.multimodal import Audio import base64 client instructor.from_openai(OpenAI()) class Person(BaseModel): name: str age: int with open(./output.wav, rb) as f: encoded_string base64.b64encode(f.read()).decode(utf-8) resp client.chat.completions.create( modelgpt-4o-audio-preview, response_modelPerson, modalities[text], audio{voice: alloy, format: wav}, messages[ { role: user, content: [ Extract the following information from the audio, Audio.from_path(./output.wav), ], }, ], ) # type: ignore print(resp) # Person(nameJason, age20)两种方式下instructor 都会把消息内容中的Audio对象转换为 OpenAI 期望的input_audio结构。Audio 辅助类的完整方法矩阵Audio与图片的Image、PDF 的PDF一样是 instructor 多模态统一接口的一部分。在 docs/concepts/multimodal.md 中给出了完整的支持矩阵MethodOpenAIGoogle GenAIfrom_url()✅✅from_gs_url()✅✅from_path()✅✅from_base64()✅✅autodetect()✅✅注意目前仅 OpenAI 与 Gemini 支持音频输入对 Geminiinstructor 默认以原始 bytes 传入也可改用 Files API详见 docs/integrations/genai.md。各方法的行为在 instructor/v2/core/multimodal.py 中均有实现from_path(path)校验文件存在且非空通过mimetypes.guess_type推断 MIME 类型audio/x-wav会归一化为audio/wavWindows 下的audio/vnd.dlna.adts会归一化为audio/aac随后读取文件字节并 base64 编码类型不在VALID_AUDIO_MIME_TYPES列表aac/flac/mp3/m4a/mpeg/mpga/mp4/opus/pcm/wav/webm中会抛ValueError。from_url(url)内部调用fetch_remote_content拉取远端内容按MAX_AUDIO_BYTES限制大小相关常量定义于 instructor/v2/core/remote.py校验Content-Type后 base64 编码。from_gs_url(gs_url)把gs://转换为https://storage.googleapis.com/...公共 URL 后再抓取因此要求对象必须公开可读默认超时 30 秒。from_base64(data_uri)解析data:audio/...;base64,前缀并校验媒体类型。autodetect(source)自动判断输入是 base64、HTTP(S) URL、GCS URL 还是本地路径分派给对应方法。关于autodetect_imagesTrueinstructor 还提供了autodetect_imagesTrue参数把 URL、GCS URL、本地路径等作为普通字符串放入消息内容时系统会自动检测并转换为对应的Image/Audio/PDF对象核心逻辑为 instructor/v2/core/multimodal.py 中的autodetect_media与convert_messages。不过对音频输入推荐显式使用Audio.from_*更利于校验与可读性。输入格式约束OpenAI 只接受 WAV 或 MP3这是最容易踩坑的一点。在 instructor/v2/providers/openai/multimodal.py 的audio_to_openai中只有audio/mp3、audio/mpeg、audio/mpga统一映射为mp3与audio/wav、audio/x-wav统一映射为wav被接受其他格式例如audio/aac会直接抛出ValueError而不是发送标签错误的字节给 API 解码失败。对应的测试用例见 tests/v2/test_core_multimodal_runtime.pydef test_audio_to_openai_format_follows_media_type() - None: from instructor.v2.providers.openai.multimodal import audio_to_openai mp3 Audio(sourceclip.mp3, media_typeaudio/mpeg, dataZmFrZQ) assert audio_to_openai(mp3, Mode.TOOLS)[input_audio][format] mp3 wav Audio(sourceclip.wav, media_typeaudio/wav, dataZmFrZQ) assert audio_to_openai(wav, Mode.TOOLS)[input_audio][format] wav aac Audio(sourceclip.aac, media_typeaudio/aac, dataZmFrZQ) with pytest.raises(ValueError, matchExpected WAV or MP3): audio_to_openai(aac, Mode.TOOLS)Audio对象最终会转换为如下 OpenAI 消息内容块类型为input_audio{ type: input_audio, input_audio: { data: base64-encoded audio bytes, format: wav } }基于 URL 与 GCS 的音频提取示例音频不一定来自本地文件。下面是 docs/concepts/multimodal.md 中给出的两种来源的完整示例示例音频为仓库测试资源tests/assets/gettysburg.wav对应的公开地址即盖茨堡演讲录音from pydantic import BaseModel import instructor from instructor.processing.multimodal import Audio # Initialize the client client instructor.from_provider(openai/gpt-4o-audio-preview) # Define our response model class AudioDescription(BaseModel): summary: str transcript: str url https://raw.githubusercontent.com/instructor-ai/instructor/main/tests/assets/gettysburg.wav # Make the API call with the audio file resp client.create( response_modelAudioDescription, modalities[text], audio{voice: alloy, format: wav}, messages[ { role: user, content: [ Extract the following information from the audio:, Audio.from_url(url), ], }, ], ) print(resp) summaryThis excerpt is from a famous historical speech discussing the founding principles of equality and liberty, and the ongoing civil war testing the endurance of those principles. transcriptFour score and seven years ago our fathers brought forth on this continent a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal. Now we are engaged in a great civil war, testing whether that nation, or any nation so conceived and so dedicated, can long endure. GCS 版本只是把来源换成Audio.from_gs_url(gs://my-bucket/path/to/audio.wav)其余参数完全一致gs_url gs://my-bucket/path/to/audio.wav resp client.create( response_modelAudioDescription, modalities[text], audio{voice: alloy, format: wav}, messages[ { role: user, content: [ Extract the following information from the audio:, Audio.from_gs_url(gs_url), ], }, ], )注意 GCS 对象必须公开可读否则from_gs_url会抛出ValueError(Failed to access GCS audio (must be publicly readable))。从音频提取扩展到通用多模态虽然本篇文章聚焦音频但理解 instructor 的Audio在消息内容中的位置有助于你在更复杂的场景中组合使用。instructor 把Image、Audio、PDF统一为多模态内容对象消息的content可以是文本 多模态对象的列表。以 docs/concepts/multimodal.md 中 PDF 发票解析为例import instructor from pydantic import BaseModel from instructor.processing.multimodal import PDF # Set up the client url https://raw.githubusercontent.com/instructor-ai/instructor/main/tests/assets/invoice.pdf client instructor.from_provider(openai/gpt-4.1-mini) # Create a model for analyzing PDFs class Invoice(BaseModel): total: float items: list[str] # Load and analyze a PDF response client.create( response_modelInvoice, messages[ { role: user, content: [ Analyze this document, PDF.from_url(url), ], } ], ) print(response) total220.0 items[English Tea - 2 units at $100 each, Tofu - 10 units at $2 each] 这说明一条消息里混排文本 多种媒体是统一设计convert_contents会根据当前模式把Audio/Image/PDF分派到对应 provider 的编码器。可进一步参考 tests/multimodal/test_multimodal.py 与 tests/v2/test_core_multimodal_runtime.py 中的运行时验证。使用场景语音助手构建更自然、更具上下文感知能力的语音交互界面把用户语音直接解析为意图/实体结构化数据。音频内容分析从录音、播客中自动提取信息、要点或情绪例如上面的AudioDescriptionsummary transcript。语言学习工具开发能听懂并回应口语的交互式语言学习应用语音识别 结构化反馈。无障碍功能通过音频交互与文本转语音能力改善应用可访问性把语音输入 → 结构化结果作为无障碍链路的一环。注意事项与限制延迟定位该功能最适合对极低延迟要求不高的异步场景需要动态、实时交互时OpenAI 官方推荐使用 Realtime API。格式限制OpenAI Chat Completions 音频输入仅接受 WAV / MP3务必在上游先把音频转成这两种格式之一。Responses API 不支持音频从 instructor/v2/providers/openai/multimodal.py 可以看到audio_to_openai在RESPONSES_TOOLS模式下会直接抛ValueError(OpenAI Responses doesnt support audio)音频结构化输出应使用 Chat Completions 相关模式。模型可用性示例中的gpt-4o-audio-preview为 OpenAI 的预览模型实际接入前请确认你的账号可用模型列表与当前模型 ID模型选择参考 docs/integrations/model-selection.mdinstructor.from_provider的第一个参数传入的是结构化输出所用的模型二者可以不同但请按你的实际账号配置调整。伦理与偏差与所有 AI 功能一样需评估音频处理与生成中的伦理问题与潜在偏差在真实用户群体上充分测试。相关文档Multimodal Guide —— 多模态Image / Audio / PDF综合参考OpenAI Integration —— OpenAI 完整接入指南Gemini Multimodal —— 另一套多模态实现Prompt Caching —— 大音频文件的缓存处理Monitoring with Logfire —— 跟踪多模态处理过程【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考