批量任务失败？教你排查GLM-TTS JSONL格式错误
当你点击「 开始批量合成」后，进度条卡在0%、日志里反复出现红色报错、或者生成的ZIP包里空空如也——别急着重装模型或怀疑GPU坏了。90%以上的批量任务失败，根源不在模型本身，而藏在那个看似简单的JSONL文件里。
GLM-TTS的批量推理功能强大且实用：支持上百个任务并行处理、自动命名输出、保留原始路径结构、失败任务自动跳过不中断整体流程。但它的鲁棒性有一个明确前提：输入必须是严格合规的JSONL。不是“差不多能读”，而是每一行都必须通过JSON解析器校验，每一个字段名都必须拼写准确，每一个路径都必须真实存在。
本文不讲原理、不堆参数，只聚焦一个目标：让你5分钟内定位并修复JSONL错误，让批量任务真正跑起来。无论你是第一次尝试批量配音的运营同学，还是正在搭建自动化语音流水线的工程师，这些排查方法都经过真实生产环境验证。
1. JSONL不是JSON——先搞清基本规则
1.1 什么是JSONL？为什么必须用它？
JSONL（JSON 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：多行JSON（JSONL要求单行一个对象） { "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。它不会“智能容错”，也不会跳过注释或空白行。
1.2 字段名大小写与必填项——零容忍区
GLM-TTS批量接口对字段名完全区分大小写，且仅识别以下四个字段：
| 字段名 | 是否必填 | 说明 | 常见错误 |
|---|---|---|---|
prompt_audio | 必填 | 参考音频绝对路径或相对于项目根目录的相对路径 | 拼成prompt_audio_path、audio_path、prompt_wav |
input_text | 必填 | 要合成的文本内容，支持中文、英文、标点 | 写成text、content、input |
prompt_text | 可选 | 参考音频对应的原文（用于提升音色对齐） | 拼成ref_text、prompt_txt、漏掉下划线 |
output_name | 可选 | 输出文件名（不含扩展名），默认为output_0001等递增编号 | 写成filename、name、包含.wav后缀 |
注意：
prompt_text和output_name即使不填，也不能留空字段。正确写法是直接省略该字段，而不是写"prompt_text": ""。
1.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_01.wav），路径一律用examples/prompt/xxx.wav格式。
2. 三步快速诊断法——从日志定位根本原因
当批量任务失败时，不要凭感觉猜。打开WebUI右下角的「日志」面板（或查看终端中python app.py的输出），按以下三步精准定位：
2.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: 'xxx' | prompt_audio路径错误 | 进入服务器执行ls -l /root/GLM-TTS/xxx验证文件是否存在 |
KeyError: 'prompt_audio'或KeyError: 'input_text' | 字段名拼写错误或缺失必填字段 | 逐行检查字段名是否为小写、下划线、完整拼写 |
UnicodeDecodeError: 'utf-8' codec can't decode byte | 文件编码非UTF-8（如GBK、ANSI） | 用文本编辑器另存为UTF-8编码 |
小技巧：在终端中用
head -n 5 your_tasks.jsonl | cat -A可同时查看前5行内容和所有隐藏字符。
2.2 第二步：定位出错行号
GLM-TTS日志会明确提示第几行解析失败：
[ERROR] Failed to parse line 7 in tasks.jsonl: JSONDecodeError: ...立即打开文件，跳转到第7行（注意：文本编辑器行号从1开始，与日志一致）。重点检查这一行及前后3行——因为JSONL错误常具有传染性（如上一行少了一个引号，导致下一行被连读解析）。
2.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行，直到复现错误——这就是“二分法定位法”。
3. 实战修复指南——高频错误场景与解决方案
下面列出5个真实用户踩过的坑，附带可直接复制的修复代码和操作命令。
3.1 场景一：Excel导出的CSV转JSONL，含乱码和引号
现象：用Excel编辑任务列表，另存为CSV，再用Python脚本转JSONL，结果批量失败。
根因：Excel CSV默认用双引号包裹含逗号的字段，且可能插入BOM头；转JSONL时未做清洗。
修复方案（Linux终端一键执行）：
# 1. 移除BOM头（如果存在） sed -i '1s/^\xEF\xBB\xBF//' tasks_from_excel.csv # 2. 使用csvformat转换为标准JSONL（需安装csvkit：pip 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。
3.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-9._-]/_/g' | sed 's/__\+/_/g' | sed 's/^_//;s/_$//') [ "$f" != "$newname" ] && mv "$f" "$newname" done临时验证：在JSONL中用URL编码替换空格（%20）和中文（如%E4%BD%A0%E5%A5%BD），但不推荐长期使用，编码易出错。
3.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」设置，确保保存时自动清理。
3.4 场景四：混合使用单引号和双引号
现象：JSONL在浏览器中能预览，但GLM-TTS报错。
根因：JSON标准只允许双引号，单引号是JavaScript扩展，不被Pythonjson模块支持。
修复方案（一键替换）：
# 将所有单引号替换为双引号，但保留字符串内的单引号（如 "it's"） 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, 1): line = line.strip() if not line: continue try: obj = json.loads(line) print(json.dumps(obj, ensure_ascii=False)) except Exception as e: print(f'Line {i} error: {e}') raise " > cleaned.jsonl3.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.mp3'); print(sr)"若报错No backend found，则需安装ffmpeg：
conda install -c conda-forge ffmpeg # 或 apt-get update && apt-get install -y ffmpeg终极保险方案：所有音频统一转为WAV（16bit, 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" done4. 预防胜于治疗——建立健壮的JSONL生成流程
与其每次出错再救火，不如从源头杜绝问题。以下是团队已验证的标准化流程：
4.1 模板化生成（推荐给非技术人员）
创建Excel模板glm-tts-batch-template.xlsx，含四列：
- A列：
prompt_audio（填写相对路径，如examples/prompt/speaker_a.wav） - B列：
input_text（要合成的文本，支持换行，但JSONL中会转为\n） - C列：
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", encoding="utf-8") 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_ascii=False) + "\n") print(" JSONL已生成：batch_tasks.jsonl")4.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 2>&1; then echo " JSONL语法正确" # 检查必填字段 if ! awk -F'"' '{for(i=1;i<=NF;i++) if($i=="prompt_audio" || $i=="input_text") c++} END{if(c!=NR*2) 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 fi5. 总结：批量任务成功的三个铁律
排查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对象，恭喜你，批量之旅已经启程。
--- > **获取更多AI镜像** > > 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_blog_end)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
