基于 agno 与 Gemini 的音频分类实战语言识别与置信度路由【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno导读本文围绕 agno 仓库中cookbook/data_labeling/_10_audio_classification的音频分类示例展开讲解如何为音频片段从封闭标签集合中分配单一标签语言识别并通过output_schema约束模型输出为结构化结果、通过confidence字段支持下游路由决策。读完本文你将掌握 agno 中「音频输入Audio 结构化输出Pydantic Schema」这一可复用的分类原语以及如何将其迁移到语种路由、音乐流派打标、客服音频情绪门控等场景。目录音频分类原语从文本分类到音频输入的同一套逻辑运行环境与前置条件基础版basic.py单标签语言识别升级版with_confidence.py带置信度的结构化输出测试结果分析TEST_LOG源码视角Audio、RunOutput与output_schema的底层原理应用场景与扩展方向1. 音频分类原语从文本分类到音频输入的同一套逻辑音频分类在 agno 的数据标注示例中与文本分类共享同一套原语primitive从封闭集合closed set中为一条输入分配一个标签。区别仅在于输入模态——文本分类传入的是字符串而音频分类传入的是Audio媒体对象。正如 README.md 所述Assign a label to an audio clip. Same primitive as text classification with audio input.这种设计让分类任务的逻辑定义标签集合 → 构建 Agent → 传入输入 → 拿到结构化结果完全独立于输入模态因此可以快速把已有的文本分类流程迁移到音频域。从源码结构看这一原语的三个关键支柱分别是支柱作用对应仓库文件Audio媒体类统一封装音频的字节内容、URL、文件路径及元数据media.pyPydantic 模型 Literal定义封闭标签集合与输出结构示例中的Classification模型output_schema让 Agent 按给定 Schema 结构化输出agent.py2. 运行环境与前置条件运行两个示例脚本需要满足以下条件Python 环境已安装 agno 及其依赖requests、pydantic、rich模型 API Key示例使用 Gemini 模型需要配置GOOGLE_API_KEY环境变量网络访问示例脚本从 agno 公共 S3 桶下载测试音频QA-01.mp3。运行命令README.mdpython cookbook/data_labeling/_10_audio_classification/basic.py python cookbook/data_labeling/_10_audio_classification/with_confidence.py按 TEST_LOG.md 记录示例曾在2026-07-18 针对gemini-3.5-flash、agno 2.7.4环境验证通过。模型替换说明两个脚本都通过modelgoogle:gemini-3.5-flash字符串指定模型。README 明确指出只要有具备原生音频输入能力的模型可以替换为其他提供商的模型字符串。3. 基础版basic.py单标签语言识别basic.py 实现最基础的音频分类为一段音频分配一个语言标签。3.1 定义封闭标签集合分类的关键是把输出约束到有限集合内Pydantic 的Literal类型天然适合表达「封闭集合」from typing import Literal from pydantic import BaseModel, Field class Classification(BaseModel): language: Literal[ english, spanish, french, german, mandarin, hindi, other ] Field(..., descriptionPrimary language spoken in the clip)这里Field(..., description...)提供字段语义描述帮助模型理解每个字段的含义Literal则从类型层面锁定可选值域——模型只能返回这 7 个值之一other作为兜底标签避免出现集合外答案。3.2 构建 Agentfrom agno.agent import Agent agent Agent( modelgoogle:gemini-3.5-flash, instructionsYou classify audio clips by spoken language., output_schemaClassification, )关键参数model指定 Gemini 模型支持原生音频输入instructions任务级指令告知 Agent 其职责是「按口语对音频片段分类」output_schema传入 Pydantic 模型类让 Agent 的输出被解析为该 Schema 的实例。3.3 下载音频并运行import requests from agno.agent import Agent, RunOutput from agno.media import Audio url https://agno-public.s3.us-east-1.amazonaws.com/demo_data/QA-01.mp3 audio_bytes requests.get(url).content run: RunOutput agent.run( What language is spoken in this audio?, audio[Audio(contentaudio_bytes)], ) pprint({url: url, result: run.content})运行流程拆解用requests下载 MP3 字节流将字节流包装为Audio(contentaudio_bytes)对象放入audio[...]列表传入agent.run()在run提示词中提出分类问题从返回的RunOutput.content中取出结构化结果Classification实例。4. 升级版with_confidence.py带置信度的结构化输出with_confidence.py 在基础版之上扩展了置信度字段其设计动机见文件头部注释是让下游路由能够区分对待低置信度标签——例如升级到更强模型、或进入人工审核队列。4.1 扩展 Schemaclass Classification(BaseModel): language: Literal[ english, spanish, french, german, mandarin, hindi, other ] Field(..., descriptionPrimary language spoken in the clip) confidence: Literal[high, medium, low] Field( ..., descriptionConfidence in the language label )新增的confidence字段同样是Literal封闭集合high / medium / low与language一起构成二元结构化输出。4.2 用 Instructions 精确定义置信度层级单纯让模型输出 confidence 字段还不够——不同模型对「high」的直觉理解可能不一致。示例通过指令定义每个层级的操作化标准来消除歧义instructions \ Identify the language and report a confidence: - high - clear speech, accent is identifiable, no background interference - medium - speech is audible but accent / dialect is ambiguous - low - very short, heavily accented, mixed-language, or noisy 这套判据是可落地的high语音清晰、口音可辨识、无背景干扰medium语音可听清但口音/方言存在歧义low片段极短、口音浓重、多语混杂或噪声明显。指令将抽象概念置信度映射为可观察的音频特征让不同输入的评分标准保持一致。这对后续「按置信度路由」至关重要——路由逻辑的正确性依赖置信度标注的稳定性。4.3 运行agent Agent( modelgoogle:gemini-3.5-flash, instructionsinstructions, output_schemaClassification, ) run: RunOutput agent.run( Identify the language and report confidence., audio[Audio(contentaudio_bytes)], ) pprint({url: url, result: run.content})5. 测试结果分析TEST_LOGTEST_LOG.md 记录了针对同一段音频QA-01.mp3的两个脚本的实测结果5.1basic.py测试记录项目结果状态PASS测试方式下载 MP3让带output_schema的 Gemini Agent 从封闭 Literal 集合中分配单一语言标签输出Classification(languageenglish)成本指标单次模型调用1921 输入 token / 6 输出 token耗时2.36s5.2with_confidence.py测试记录项目结果状态PASS测试方式同一识别任务Schema 扩展confidenceLiteral 字段并用指令定义各置信度层级以支撑下游路由输出Classification(languageenglish, confidencehigh)成本指标单次模型调用1965 输入 token / 12 输出 token耗时1.67s5.3 观察要点两个脚本均为单次模型调用说明音频分类无需多轮交互结构化输出在单轮内即可完成with_confidence.py仅增加 44 个输入 token来自更长的指令和 6 个输出 token新增字段说明置信度扩展的边际成本极低两次测试对同一段音频都判定为english且置信度版给出high与指令定义中「语音清晰、口音可辨识」的判据一致说明指令约束起到了稳定标注的作用耗时在 2 秒量级适合对延迟敏感的批量标注或实时路由场景。需要说明以上 token 数与耗时为特定测试环境gemini-3.5-flash、agno 2.7.4、单段音频下的实测记录不同模型、音频时长与网络环境下会有差异仅作参考。6. 源码视角Audio、RunOutput与output_schema的底层原理6.1Audio媒体类的统一封装音频输入在 agno 中统一由Audio类承载定义于 media.py注释将其定位为「Unified Audio class for all use cases (input, output, artifacts)」。核心字段包括内容来源三选一url远程地址、filepath本地路径、content原始音频字节统一标准化为bytes格式元数据format如mp3、wav、ogg、mime_type如audio/mpeg、audio/wav音频专属元数据duration时长秒数、sample_rate采样率默认 24000 Hz、channels声道数默认 1输出侧字段transcript模型返回的转写文本、expires_at临时 URL 过期时间戳存储与自定义字段media_reference媒体外置到对象存储时的引用、metadata用户自定义元数据。从validate_and_normalize_content校验器的实现可以推断Audio要求内容来源「恰好一个」URL、文件路径或字节内容三选一并通过model_validator做规范化保证进入模型调用链前的内容形态一致。示例中采用的Audio(contentaudio_bytes)即字节直传方式是最轻量的用法。6.2RunOutput返回结构agent.run()的返回值类型为RunOutput定义于 run/agent.py。该数据类除了content本次示例取用的结构化结果外还包含运行标识run_id、agent_id、session_id、parent_run_id、workflow_id输入回显inputRunInput、messages推理信息reasoning_content、reasoning_steps、reasoning_messages媒体与文件images、videos、audio、files、response_audio引用与指标citations、references、followups、metrics、tools等。也就是说示例脚本只展示了RunOutput的冰山一角——在生产环境中metricstoken 消耗与耗时、messages完整对话记录都是可用的分析数据。6.3output_schema的类型与生效方式output_schema是Agent构造参数之一定义于 agent/agent.py其类型为Optional[Union[Type[BaseModel], Dict[str, Any]]]——即既可以传 Pydantic 模型类也可以传 JSON Schema 字典。示例中传入Classification模型类模型被要求直接产出符合该 Schema 的结构化输出而非自由文本。这一机制是 agno 结构化输出能力在音频任务上的复用在basic.py与with_confidence.py中output_schema与Audio媒体输入协同工作模型在理解音频内容的同时按 Schema 生成 JSON 化结果再由 agno 解析为Classification实例返回。7. 应用场景与扩展方向README 列出的典型场景包括多语言语音信箱系统的语种路由先识别语种再路由到对应语言的 IVR 或座席队列音乐库的流派打标把language标签换成genre标签同一套 Schema 逻辑直接复用客服音频的情绪/语气门控把标签换成tone如 positive / neutral / negative可配合置信度做升级处理。以with_confidence.py的置信度字段为例一个实用的下游路由策略是置信度处理策略high直接采用进入自动分类管道medium采用但标记供后续抽样复核low升级到更强模型重新判断或进入人工审核队列扩展方向还包括将标签集合从Literal迁移到动态配置例如多语言场景中按租户维护语言列表、将置信度扩展为连续分值、或在audio[...]列表中一次传入多段音频实现批量标注。参考文件audio_classification/README.mdaudio_classification/basic.pyaudio_classification/with_confidence.pyaudio_classification/TEST_LOG.mdmedia.py 中 Audio 类定义agent.py 中 output_schema 参数定义run/agent.py 中 RunOutput 类定义【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考