JSONL 文件:如何为 AI 上传一步步创建
简短回答 JSONL 文件是纯文本,每行一个完整的 JSON 对象,以 UTF-8 保存,扩展名为 .jsonl。制作方法:把表格另存为 CSV,运行一段简短的 Python 脚本,每行数据写一行,然后检查每一行都能被解析。动手前,先确认您的 AI 平台要求的确切字段。
想把这些用到您的生意上?预约一次 30 分钟的免费通话,一起聊聊。
预约通话如何创建 JSONL 文件:四个步骤
从一张表格开始,最后得到 AI 平台能接受的文件。Python 免费,做这件事也不需要安装额外的包。
| 步骤 | 做什么 | 容易出错的地方 |
|---|---|---|
| 1. 弄清目标格式 | 阅读您要上传的平台的上传说明页面 | 每个平台的字段名都不一样 |
| 2. 把数据存为 CSV | 每行一个示例,每列一个字段,第 1 行是表头 | 合并单元格和表格下方的备注会变成垃圾行 |
| 3. 用 Python 转换 | 一段三行脚本,每行数据写成一个 JSON 对象 | 把整个列表写成一个 JSON 数组 |
| 4. 逐行检查 | Python 自带的检查工具逐行读取,遇到第一处错误就停下 | 一个空行或一个多余的逗号就会让整个上传失败 |
JSONL 文件长什么样
每行是一条记录,每条记录本身都是完整的。JSON Lines 格式有三条规则:文件为 UTF-8,每行是一个有效的 JSON 值,每行以换行符结尾。有两个细节常让人出错:
"a byte order mark (U+FEFF) must NOT be included" (JSON Lines specification) 译文:“不得包含字节顺序标记(U+FEFF)”
"e.g. null is a valid value but a blank line is not." (JSON Lines specification) 译文:“例如,null 是有效值,但空行不是。”
最后一条记录后面加换行符是“strongly recommended but not required”(强烈建议,但不是必须)。常用扩展名是 .jsonl。
| 普通 JSON | JSONL | |
|---|---|---|
| 结构 | 一个大的对象或数组,常跨很多行 | 每行一个对象,没有外层括号,行与行之间没有逗号 |
| 程序如何读取 | 通常一次读完 | 一次读一行 |
| 添加一条记录 | 在数组里面编辑 | 在末尾加一行 |
| 一条记录损坏 | 整个文件解析失败 | 只有那一行失败,其余照常读取 |
批量任务中的一行简短内容如下,在文件里它全部写在同一行:
{"custom_id": "faq-1", "method": "POST", "url": "/v1/responses", "body": {"model": "...", "input": "Write a 2-sentence answer: do you work Saturdays?"}}
哪些 AI 工具要求 JSONL 文件?
主要是两类工作:用您的示例训练模型(微调),以及一次性以折扣价发送大量请求(批量处理)。动手之前先看平台自己的说明页面,因为字段名各不相同。
| 平台 | JSONL 的用途 | 主要限制(2026 年 11 月) |
|---|---|---|
| OpenAI Batch API | 一次发送大量请求;每行需要唯一的 custom_id | 比普通调用便宜 50%;24 小时内完成;每个文件最多 50,000 个请求、200 MB;每个文件只能用一个模型 |
| Gemini API Batch | 一次发送大量请求;每行有一个 key 和一个 request | 标准费用的 50%;目标 24 小时完成;输入文件最大 2 GB |
| Google Cloud(Gemini 微调) | 微调,每行一个示例,上传到 Cloud Storage | Google 建议从 100 个示例开始 |
| Amazon Bedrock | 微调;格式取决于模型 | 每个模型有各自的大小规定 |
| Microsoft Foundry | 微调;训练文件和验证文件分开,每行一段对话 | 每个模型有示例数量和大小的最低要求 |
| OpenAI 微调 | 即将关闭;见下文 | 至少 10 行;OpenAI 建议从 50 行开始 |
大多数旧教程都基于 OpenAI 的微调,而它正在关闭:
"OpenAI is winding down the fine-tuning platform. The platform is no longer accessible to new users." (OpenAI API docs: Supervised fine-tuning) 译文:“OpenAI 正在逐步关闭微调平台。新用户已无法使用该平台。”
符合条件的现有客户在 2027 年 1 月 6 日之前仍可启动训练任务,gpt-4.1 和 gpt-4.1-mini 的微调模型将于 2027 年 1 月 14 日停用。如果您是新用户,请改用 Google Cloud、Bedrock 或 Foundry,或者干脆不做微调。
您真的需要微调吗?
通常不需要。老板们的大多数工作,比如用您的口吻回答常见问题或起草报价,用一个好的提示词再贴几个示例就能完成。OpenAI 自己的建议也是先测试:“Only invest in fine-tuning after setting up evals”(先建立评估,再投入微调);如果 50 个好示例都没有带来改变,就要“rethink your task or prompt before adding training data”(在增加训练数据之前,重新思考您的任务或提示词)。先从更好的提示词开始,等它们到了瓶颈再回来。
用 Python 把表格转成 JSONL
把表格另存为 CSV(在 Excel 中选择 CSV UTF-8)。然后把下面几行放进一个文件(例如 convert.py)运行,把文件名换成您自己的:
import csv, jsonrows = csv.DictReader(open("faq.csv", encoding="utf-8-sig", newline=""))with open("faq.jsonl", "w", encoding="utf-8") as f: f.writelines(json.dumps(r, ensure_ascii=False) + "\n" for r in rows)
每个部分的作用:
| 部分 | 作用 |
|---|---|
| csv.DictReader | 把每行变成一条记录,以第 1 行作为字段名 |
| utf-8-sig | 据 Python 文档,如果文件开头有隐藏的字节顺序标记,它会跳过,这样第一列的列名保持干净 |
| json.dumps(...) + "\n" | 一条记录,再加一个换行:这就是 JSONL 的全部规则 |
| ensure_ascii=False | 让重音符号和非英文字符保持可读,而不是变成转义码 |
| encoding="utf-8" | 以 UTF-8 写入,不带格式所禁止的标记 |
已经在用 pandas?一行就能完成同样的工作:pd.read_csv("faq.csv").to_json("faq.jsonl", orient="records", lines=True, force_ascii=False)。根据 pandas 文档,lines 选项只有在 orient 设为 records 时才有效。
如何编写微调示例
对话式训练文件把每个示例包在一个 messages 列表里:客户问了什么,以及您希望得到的回答。这是 Microsoft Foundry 展示的结构。如果 CSV 有 question 和 answer 两列,把脚本第 3 行改成:
with open("train.jsonl", "w", encoding="utf-8") as f: f.writelines(json.dumps({"messages": [{"role": "user", "content": r["question"]}, {"role": "assistant", "content": r["answer"]}]}, ensure_ascii=False) + "\n" for r in rows)
这样每行数据会变成这样的一行:
{"messages": [{"role": "user", "content": "Do you work Saturdays?"}, {"role": "assistant", "content": "Yes, 8am to 2pm."}]}
Google 的 Gemini 微调用的是不同的名称(contents 和 parts,可选 systemInstruction),所以同样的思路在那里要换用不同的键。无论哪个平台,都要用真实的问题和您最好的员工给出的回答。另外留一组示例不参与训练,用来测试结果。
上传前检查文件
Python 自带检查工具。在终端运行:
python3 -m json.tool --json-lines faq.jsonl
它把每一行当作独立的 JSON 对象读取(Python 3.8 起提供)。如果每行都没问题,它会全部打印出来。如果有问题,它会报错停下;最后打印出的那条记录是最后一行正确的内容,所以问题出在下一行。
| 您看到的错误 | 常见原因 | 解决方法 |
|---|---|---|
| Expecting value | 一个空行,常出现在粘贴的文件末尾 | 删除空行 |
| Expecting property name enclosed in double quotes | 手动输入时用了单引号或多了结尾逗号 | 用脚本生成各行,不要手打 |
| 上传被拒,格式看起来没问题 | 字段名和平台不一致 | 拿一行和平台给的示例对照 |
| 运行脚本时出现 UnicodeDecodeError | CSV 用旧编码保存,不是 UTF-8 | 重新另存为 CSV UTF-8 再运行 |
不用 Python 能做 JSONL 文件吗?
能,只要行数不多。在纯文本编辑器(Notepad、纯文本模式下的 TextEdit)里输入,每行一条记录,以 UTF-8 保存,扩展名为 .jsonl。超过 20 行左右,手打就容易出现上面那些错误。
网上有免费的 CSV 转 JSONL 工具,但您要把文件上传到别人的服务器。训练数据常包含客户姓名、电子邮件和工作细节,所以发送之前,先了解您如何收集这些数据、客户同意了什么。
示例
水管工的常见问题批量处理
表格里有 60 个常见问题。老板把它另存为 CSV,转换后给每行包上带 custom_id 的批量格式,一次发送一个批量任务,以正常价格的一半起草网站上的回答。检查工具事先发现了文件末尾的一个空行。
美发沙龙训练回复风格
200 条过去回复预约问题的消息,已去掉客户姓名。老板先试了一个贴了 10 个示例的提示词,草稿已经足够接近。微调就此搁置。
拿着旧 OpenAI 教程的记账师
教程说要上传到 OpenAI 微调。账户是新的,所以没有这个选项。同样的示例改用 Google 的 contents 和 parts 字段名后,改传到 Google Cloud。
常见问题
JSON 和 JSONL 有什么区别?
JSON 存放一个对象或数组,常跨很多行。JSONL 每行存放一个完整的对象,所以程序可以一次读取或添加一条记录。
能用 Excel 打开 JSONL 文件吗?
不能直接按行打开。用 pandas(read_json 加 lines=True)转回来再存为 CSV,或者用任何文本编辑器打开阅读。
微调模型需要多少示例?
取决于平台。OpenAI 的最低要求是 10 行,建议从 50 行开始;Google 建议 Gemini 微调从 100 个开始。在两个平台上,质量都比数量更重要。
大的 JSONL 文件要压缩吗?
JSON Lines 规范建议用 gzip 或 bzip2 节省空间。除非平台页面说明接受压缩文件,否则请上传未压缩的文件。
您的情况不同?
- 您希望 AI 直接完成任务,不用自己做文件: 请看 AI 营销自动化设置。
- 您的数据包含客户信息: 先看第一方数据与同意。
- 您只需要更好的 AI 输出: 从 AI 营销提示词或用 ChatGPT 做营销开始。
- 您希望网站上也有这样的回答: 请看网站智能体。