核心内容摘要
all-MiniLM-L6-v2实战案例：基于Ollama构建相似度验证系统
批量任务失败教你排查GLM-TTS JSONL格式错误当你点击「 开始批量合成」后进度条卡在0%、日志里反复出现红色报错、或者生成的ZIP包里空空如也——别急着重装模型或怀疑GPU坏了。
90%以上的批量任务失败根源不在模型本身而藏在那个看似简单的JSONL文件里。
GLM-TTS的批量推理功能强大且实用支持上百个任务并行处理、自动命名输出、保留原始路径结构、失败任务自动跳过不中断整体流程。
但它的鲁棒性有一个明确前提输入必须是严格合规的JSONL。
不是“差不多能读”而是每一行都必须通过JSON解析器校验每一个字段名都必须拼写准确每一个路径都必须真实存在。
本文不讲原理、不堆参数只聚焦一个目标让你5分钟内定位并修复JSONL错误让批量任务真正跑起来。
无论你是第一次尝试批量配音的运营同学还是正在搭建自动化语音流水线的工程师这些排查方法都经过真实生产环境验证。
JSONL不是JSON——先搞清基本规则
1 什么是JSONL为什么必须用它JSONLJSON Lines是一种纯文本数据格式每行一个独立、完整的JSON对象行与行之间用换行符分隔。
它不是JSON数组也不是缩进排版的JSON文档。
正确的JSONL两行两个任务{prompt_audio: audio/zhao.wav, input_text: 你好今天天气不错, output_name: greeting_001} {prompt_audio: audio/qian.wav, input_text: 会议将在下午三点开始, output_name: meeting_002}常见错误写法全部非法// 错误1用了方括号包裹这是JSON数组不是JSONL [{prompt_audio: ...}, {prompt_audio: ...}] // 错误2多行JSONJSONL要求单行一个对象 { prompt_audio: audio/zhao.wav, input_text: 你好 } // 错误3末尾多了逗号JSONL每行是独立JSON不允许尾逗号 {prompt_audio: audio/zhao.wav, input_text: 你好,} // 错误4中文引号、全角标点、不可见字符 {“prompt_audio”: “audio/zhao.wav”, “input_text”: “你好”} // 全角引号关键提醒GLM-TTS的批量模块使用Python标准json.loads()逐行解析。
任何不符合JSON语法的行都会导致整行解析失败并在日志中抛出JSONDecodeError。
它不会“智能容错”也不会跳过注释或空白行。
2 字段名大小写与必填项——零容忍区GLM-TTS批量接口对字段名完全区分大小写且仅识别以下四个字段字段名是否必填说明常见错误prompt_audio必填参考音频绝对路径或相对于项目根目录的相对路径拼成prompt_audio_path、audio_path、prompt_wavinput_text必填要合成的文本内容支持中文、英文、标点写成text、content、inputprompt_text可选参考音频对应的原文用于提升音色对齐拼成ref_text、prompt_txt、漏掉下划线output_name可选输出文件名不含扩展名默认为output_0001等递增编号写成filename、name、包含.wav后缀注意prompt_text和output_name即使不填也不能留空字段。
正确写法是直接省略该字段而不是写prompt_text: 。
3 路径问题——最隐蔽的“不存在”prompt_audio字段填写的是文件路径而非URL或Base64编码。
这个路径必须满足两个条件路径可访问WebUI运行时的当前工作目录是/root/GLM-TTS/由启动脚本决定因此所有路径均以此为基准。
文件真实存在路径指向的音频文件必须物理存在于服务器上且WebUI进程有读取权限。
常见路径陷阱// 错误绝对路径写错多了一个斜杠或少了一个 {prompt_audio: /root/GLM-TTS//examples/prompt/zhao.wav} // 多余// {prompt_audio: examples/prompt/zhao.wav} // 正确相对路径 {prompt_audio: ./examples/prompt/zhao.wav} // 正确带./前缀 {prompt_audio: examples/prompt/zhao.WAV} // 大小写敏感Linux系统区分大小写 // 错误路径中含空格或中文未转义多数shell会截断 {prompt_audio: examples/prompt/张三录音.wav} // 极易失败建议改用英文名 // 错误路径指向目录而非文件 {prompt_audio: examples/prompt/} // 不是文件安全实践所有音频文件统一放在examples/prompt/目录下使用纯英文数字命名如speaker_a_
wav路径一律用examples/prompt/xxx.wav格式。
三步快速诊断法——从日志定位根本原因当批量任务失败时不要凭感觉猜。
打开WebUI右下角的「日志」面板或查看终端中python app.py的输出按以下三步精准定位
1 第一步看错误类型关键词在日志顶部几行寻找以下典型错误信息日志关键词含义解决方向JSONDecodeError: Expecting property name enclosed in double quotes行首出现中文引号、单引号、全角符号检查编辑器编码必须UTF-8无BOM用VS Code或Notepad重存JSONDecodeError: Invalid control character at行中含不可见字符如Windows换行符\r\n、制表符\t、零宽空格用cat -A your_file.jsonl在Linux查看隐藏字符或粘贴到在线JSONL校验工具FileNotFoundError: [Errno 2] No such file or directory: xxxprompt_audio路径错误进入服务器执行ls -l /root/GLM-TTS/xxx验证文件是否存在KeyError: prompt_audio或KeyError: input_text字段名拼写错误或缺失必填字段逐行检查字段名是否为小写、下划线、完整拼写UnicodeDecodeError: utf-8 codec cant decode byte文件编码非UTF-8如GBK、ANSI用文本编辑器另存为UTF-8编码小技巧在终端中用head -n 5 your_tasks.jsonl | cat -A可同时查看前5行内容和所有隐藏字符。
2 第二步定位出错行号GLM-TTS日志会明确提示第几行解析失败[ERROR] Failed to parse line 7 in tasks.jsonl: JSONDecodeError: ...立即打开文件跳转到第7行注意文本编辑器行号从1开始与日志一致。
重点检查这一行及前后3行——因为JSONL错误常具有传染性如上一行少了一个引号导致下一行被连读解析。
3 第三步最小化复现——隔离问题创建一个仅含1行的测试文件test.jsonl{prompt_audio: examples/prompt/test.wav, input_text: 测试成功}确保test.wav是一个真实存在的、3秒以上的清晰人声WAV文件可用sox -n synth 3 sine 440生成测试音。
上传此文件。
如果成功则原文件问题出在其他行如果仍失败则问题在环境或基础路径配置。
验证通过后再逐步将原文件中的有效行复制到test.jsonl中每次加1行直到复现错误——这就是“二分法定位法”。
实战修复指南——高频错误场景与解决方案下面列出5个真实用户踩过的坑附带可直接复制的修复代码和操作命令。
1 场景一Excel导出的CSV转JSONL含乱码和引号现象用Excel编辑任务列表另存为CSV再用Python脚本转JSONL结果批量失败。
根因Excel CSV默认用双引号包裹含逗号的字段且可能插入BOM头转JSONL时未做清洗。
修复方案Linux终端一键执行#
移除BOM头如果存在 sed -i 1s/^\xEF\xBB\xBF// tasks_from_excel.csv #
使用csvformat转换为标准JSONL需安装csvkitpip install csvkit csvformat -D , -t tasks_from_excel.csv | \ csvsql --query SELECT prompt_audio, input_text, prompt_text, output_name FROM stdin | \ jq -r {prompt_audio: .prompt_audio, input_text: .input_text, prompt_text: .prompt_text, output_name: .output_name} | tostring | \ sed s/^//; s/$//; s/\\//g fixed_tasks.jsonl更简单做法推荐在Excel中将四列分别命名为prompt_audio,input_text,prompt_text,output_name→ 全选复制 → 粘贴到VS Code → 使用「多光标编辑」添加前后大括号和逗号 → 保存为UTF-8。
2 场景二路径含中文/空格WebUI无法读取现象日志报FileNotFoundError但ls命令显示文件存在。
根因路径中空格或中文被shell截断或WebUI内部路径解析失败。
修复方案永久解决重命名所有音频文件使用下划线替代空格拼音替代中文# 进入音频目录批量重命名示例 cd /root/GLM-TTS/examples/prompt/ for f in *; do newname$(echo $f | iconv -f UTF-8 -t ASCII//TRANSLIT | sed s/[^a-zA-Z0-
_-]/_/g | sed s/__\/_/g | sed s/^_//;s/_$//) [ $f ! $newname ] mv $f $newname done临时验证在JSONL中用URL编码替换空格%20和中文如%E4%BD%A0%E5%A5%BD但不推荐长期使用编码易出错。
3 场景三最后一行多了换行符导致空行解析失败现象日志报JSONDecodeError: Extra data且错误行号为文件末尾。
根因文本编辑器在文件末尾自动添加了空行JSONL不允许空行。
修复方案Linux# 删除文件末尾所有空行 sed -i :a;/^\s*$/{$d;N;ba;} tasks.jsonl # 或更简单用truncate删除最后一字节如果确定是多余换行 truncate -s -1 tasks.jsonl预防在VS Code中开启「Files: Insert Final Newline」和「Files: Trim Final Newlines」设置确保保存时自动清理。
4 场景四混合使用单引号和双引号现象JSONL在浏览器中能预览但GLM-TTS报错。
根因JSON标准只允许双引号单引号是JavaScript扩展不被Pythonjson模块支持。
修复方案一键替换# 将所有单引号替换为双引号但保留字符串内的单引号如 its sed -i s/\\([^]*\)\/\\1\/g; s/^\/\/; s/\$/\/ tasks.jsonl # 更可靠用Python脚本清洗推荐 python3 -c import json, sys with open(tasks.jsonl) as f: for i, line in enumerate(f,
: line line.strip() if not line: continue try: obj json.loads(line) print(json.dumps(obj, ensure_asciiFalse)) except Exception as e: print(fLine {i} error: {e}) raise cleaned.jsonl
5 场景五音频文件格式不支持MP3未解码现象日志无明显错误但生成的WAV文件时长为0秒或播放无声。
根因GLM-TTS底层依赖librosa加载音频而librosa默认不支持MP3需额外安装ffmpeg。
修复方案确认是否支持MP3# 进入虚拟环境 source /opt/miniconda3/bin/activate torch29 python3 -c import librosa; y, sr librosa.load(examples/prompt/test.mp
; print(sr)若报错No backend found则需安装ffmpegconda install -c conda-forge ffmpeg # 或 apt-get update apt-get install -y ffmpeg终极保险方案所有音频统一转为WAV16bit, 16kHz, 单声道# 批量转换需安装sox apt-get install -y sox for f in examples/prompt/*.mp3; do sox $f -r 16000 -b 16 -c 1 ${f%.mp3}.wav done
预防胜于治疗——建立健壮的JSONL生成流程与其每次出错再救火不如从源头杜绝问题。
以下是团队已验证的标准化流程
1 模板化生成推荐给非技术人员创建Excel模板glm-tts-batch-template.xlsx含四列A列prompt_audio填写相对路径如examples/prompt/speaker_a.wavB列input_text要合成的文本支持换行但JSONL中会转为\nC列prompt_text参考音频原文可为空D列output_name输出名可为空导出脚本Python双击运行# save_as_jsonl.py import pandas as pd import json df pd.read_excel(glm-tts-batch-template.xlsx) # 清理空行和无效列 df df.dropna(subset[prompt_audio, input_text]) # 转义换行符 df[input_text] df[input_text].str.replace(\n, \\n) # 生成JSONL with open(batch_tasks.jsonl, w, encodingutf-
as f: for _, row in df.iterrows(): obj { prompt_audio: str(row[prompt_audio]), input_text: str(row[input_text]) } if pd.notna(row[prompt_text]): obj[prompt_text] str(row[prompt_text]) if pd.notna(row[output_name]): obj[output_name] str(row[output_name]) f.write(json.dumps(obj, ensure_asciiFalse) \n) print( JSONL已生成batch_tasks.jsonl)
2 自动化校验推荐给工程师在CI/CD或本地部署前加入JSONL校验步骤# validate_jsonl.sh #!/bin/bash if ! command -v jq /dev/null; then echo jq not installed. Run: apt-get install jq exit 1 fi if jq -e . batch_tasks.jsonl /dev/null 21; then echo JSONL语法正确 # 检查必填字段 if ! awk -F {for(i1;iNF;i) if($iprompt_audio || $iinput_text) c} END{if(c!NR*
exit 1} batch_tasks.jsonl; then echo 缺失必填字段 prompt_audio 或 input_text exit 1 fi # 检查路径是否存在仅限Linux head -n 10 batch_tasks.jsonl | while read line; do path$(echo $line | jq -r .prompt_audio 2/dev/null) if [ $path ! null ] [ -n $path ]; then if [ ! -f /root/GLM-TTS/$path ]; then echo 路径不存在: $path exit 1 fi fi done echo 全部校验通过 else echo JSONL语法错误请检查 exit 1 fi
5.
总结批量任务成功的三个铁律排查JSONL错误不是玄学而是有章可循的工程实践。
记住这三条铁律99%的问题都能迎刃而解铁律一JSONL即JSON不是“像JSON”每一行必须是独立、合法、UTF-8编码的JSON对象。
用jq . file.jsonl命令一键验证通不过就别上传。
铁律二路径即生命线一切以/root/GLM-TTS/为原点在服务器上用pwd确认当前目录用ls -l确认文件存在用file examples/prompt/test.wav确认音频格式。
眼见为实拒绝猜测。
铁律三日志即真相错误行号是第一线索GLM-TTS日志从不撒谎。
看到line 42报错就专注检查第42行及上下文。
把日志截图发给同事前先自己执行sed -n 42p tasks.jsonl看一眼。
批量语音合成的价值在于把“一次生成”变成“一百次生成”。
而这一切的前提是你能稳稳地迈出第一步——上传一个零错误的JSONL文件。
现在打开你的任务文件运行一次jq . your_file.jsonl如果屏幕刷出整齐的JSON对象恭喜你批量之旅已经启程。
--- **