使用 Instructor CLI 管理 OpenAI 微调任务从数据上传到模型监控的完整实战指南【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor本指南围绕instructor项目内置的命令行工具系统讲解如何使用instructor jobs与instructor files两大子命令在终端中创建、查看、监控和取消 OpenAI 微调fine-tuning任务。读完本文你将掌握蒸馏数据 → 上传文件 → 创建微调任务 → 实时监控 → 取消/管理的完整闭环操作并能结合项目源码理解每个命令背后的底层行为。一、Instructor CLI 概览一个面向微调任务的轻量包装层instructor不仅是一个结构化输出的 Python 库还随包附带了一套 CLI 工具用于在命令行管理 OpenAI 平台上的微调任务与文件。与许多功能繁重的 CLI 不同其设计哲学是对 API 提供轻量包装light wrapper而非完整的 CLI 替代品——正如 docs/cli/finetune.md 所述CLI 目前仍在开发中尚未覆盖 API 的全部特性。CLI 的命令树注册在 instructor/cli/cli.py 中通过 Typer 组装了四个子命令组子命令功能说明instructor jobs监控和创建微调任务本文核心含cancel、create-from-file、create-from-id、listinstructor files管理 OpenAI 服务器上的文件含upload、download、delete、status、listinstructor usage查看 API 用量与成本详见 docs/cli/usage.mdinstructor batch管理 OpenAI Batch 任务底层复用instructor/batch模块instructor docs在浏览器中打开官方文档支持传入搜索关键词CLI 入口在 pyproject.toml 中声明为instructor instructor.cli.cli:app因此安装 instructor 后即可直接使用pip install instructor export OPENAI_API_KEYyour-api-key-here一个值得注意的实现细节OpenAI 客户端采用懒加载策略。在 instructor/cli/jobs.py 与 instructor/cli/files.py 中_get_client()仅在首次调用时才实例化OpenAI()且实例会被缓存复用。对应的测试 tests/cli/test_help.py 专门验证了在未配置任何 OPENAI 凭据时--help依然能正常输出而只有真正执行读写操作如files delete、jobs cancel时才会因缺少凭据抛出OpenAIError。这意味着你可以在不配置密钥的情况下安全地浏览所有命令帮助。二、instructor jobs命令总览instructor jobs是微调任务管理的入口运行instructor jobs --help可以看到完整的子命令清单$ instructor jobs --help Usage: instructor jobs [OPTIONS] COMMAND [ARGS]... Monitor and create fine tuning jobs ╭─ Options ───────────────────────────────────────────────────────────────────────────────╮ │ --help Display the help message. │ ╰─────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────╮ │ cancel Cancel a fine-tuning job. │ │ create-from-file Create a fine-tuning job from a file. │ │ create-from-id Create a fine-tuning job from an existing ID. │ │ list Monitor the status of the most recent fine-tuning jobs. │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────╯四个子命令分别对应 instructor/cli/jobs.py 中的四个 Typer 命令函数list→watch()实时刷新监控最近任务状态create-from-file→create_from_file()一步完成上传训练文件 创建微调任务create-from-id→create_from_id()基于已上传的文件 ID 直接创建微调任务cancel→cancel()取消正在运行的微调任务。三、从文件一键创建微调任务create-from-filecreate-from-file是最高效的入口它把上传训练数据文件、等待处理、创建微调任务三个步骤压缩为一个命令。3.1 参数详解❯ instructor jobs create-from-file --help Usage: instructor jobs create-from-file [OPTIONS] FILE Create a fine-tuning job from a file. ╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────╮ │ * file TEXT Path to the file for fine-tuning [default: None] [required] │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────╮ │ --model TEXT Model to use for fine-tuning [default: gpt-5.4-mini] │ │ --poll INTEGER Polling interval in seconds [default: 2] │ │ --n-epochs INTEGER Number of epochs for fine-tuning │ │ --batch-size TEXT Batch size for fine-tuning │ │ --learning-rate-multiplier TEXT Learning rate multiplier for fine-tuning │ │ --validation-file TEXT Path to the validation file [default: None] │ │ --model-suffix TEXT Suffix to identify the model [default: None] │ │ --help Show this message and exit. │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────╯参数说明参数类型默认值作用FILE位置参数必填无训练数据文件路径JSONL 格式--modelTEXTgpt-5.4-mini用于微调的基础模型--pollINTEGER2文件上传状态轮询间隔秒--n-epochsINTEGER无训练轮数epochs--batch-sizeTEXT无微调批大小--learning-rate-multiplierTEXT无学习率乘数--validation-fileTEXT无验证集文件路径--model-suffixTEXT无微调后模型的标识后缀3.2 典型用法$ instructor jobs create-from-file transformed_data.jsonl --validation_file validation_data.jsonl --n_epochs 3 --batch_size 16 --learning_rate_multiplier 0.5注意--n_epochs、--batch_size、--learning_rate_multiplier这三个超参数仅在你显式传入时才会被附加到微调请求中不传则交给 OpenAI 侧自动调度。3.3 底层实现一步式工作流如何运转从源码 instructor/cli/jobs.py 可以清晰还原该命令的执行链路上传训练文件以purposefine-tune调用client.files.create()上传训练文件拿到file_id可选上传验证文件若指定了--validation-file同样以purposefine-tune上传得到validation_file_id轮询等待处理循环调用get_file_status()内部是client.files.retrieve()以--poll指定的间隔轮询直到文件状态变为processed才继续轮询期间终端会显示 Monitoring upload: {file_id} before finetuning... 的进度提示构造超参数仅当n_epochs/batch_size/learning_rate_multiplier非空时才将它们组装进hyperparameters字典创建微调任务调用client.fine_tuning.jobs.create(training_filefile_id, modelmodel, **additional_params)其中validation_file与suffix来自--model-suffix会被映射为对应的 API 参数自动进入监控任务创建成功后命令末尾自动调用watch(limit5, pollpoll, screenFalse)直接以实时监控表格收尾。该命令还通过 Typer 的类型标注对参数做了约束--n-epochs与--batch-size被定义为Optional[int]--learning-rate-multiplier为Optional[float]非法输入会在进入网络请求前被拒绝。四、基于已上传文件创建任务create-from-id如果训练文件已经上传到 OpenAI例如通过instructor files upload则无需再次上传直接引用文件 ID 创建任务即可❯ instructor jobs create-from-id --help Usage: instructor jobs create-from-id [OPTIONS] ID Create a fine-tuning job from an existing ID. ╭─ Arguments ───────────────────────────────────────────────────────────────────────────╮ │ * id TEXT ID of the existing fine-tuning job [default: None] [required] │ ╰───────────────────────────────────────────────────────────────────────────────────────╯ ╭─ Options ─────────────────────────────────────────────────────────────────────────────╮ │ --model TEXT Model to use for fine-tuning │ │ [default: gpt-5.4-mini] │ │ --n-epochs INTEGER Number of epochs for fine-tuning │ │ --batch-size TEXT Batch size for fine-tuning │ │ --learning-rate-multiplier TEXT Learning rate multiplier for fine-tuning │ │ --validation-file-id TEXT ID of the uploaded validation file │ │ [default: None] │ │ --help Show this message and exit. │ ╰───────────────────────────────────────────────────────────────────────────────────────╯与create-from-file相比区别在于位置参数从文件路径变为文件 ID验证集参数由--validation-file本地路径变为--validation-file-id已上传文件的 ID少了--poll无需等待上传与--model-suffix。典型工作流是先用instructor files子命令完成上传与查询再创建任务$ instructor files upload transformed_data.jsonl $ instructor files upload validation_data.jsonl $ instructor files list ... $ instructor jobs create_from_id file_id --validation_file validation_file_id --n_epochs 3 --batch_size 16 --learning_rate_multiplier 0.5从源码 instructor/cli/jobs.py 看create_from_id在构造hyperparameters字典后直接调用fine_tuning.jobs.create()随后同样自动转入watch(limit5, poll2, screenFalse)监控。注意命令帮助中显示的 snake_case 形式create_from_id是 Typer 的别名与 kebab-case 的create-from-id等价。五、实时监控微调任务jobs listinstructor jobs list提供了一个自动刷新的实时监控仪表盘是跟踪训练进度的主力命令。它会列出最近的任务并在终端中用 Rich 表格持续刷新$ instructor jobs list OpenAI Fine Tuning Job Monitoring ┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━┓ ┃ ┃ ┃ ┃ Completion ┃ ┃ ┃ ┃ ┃ ┃ Job ID ┃ Status ┃ Creation Time ┃ Time ┃ Model Name ┃ File ID ┃ Epochs ┃ Base Model ┃ ┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━┩ │ ftjob-PWo6uwk... │ cancelled │ 2023-08-23 │ N/A │ │ file-F7lJg6Z4... │ 3 │ gpt-5.4-mini-... │ │ │ │ 23:10:54 │ │ │ │ │ │ │ ftjob-1whjva8... │ cancelled │ 2023-08-23 │ N/A │ │ file-F7lJg6Z4... │ 3 │ gpt-5.4-mini-... │ │ │ │ 22:47:05 │ │ │ │ │ │ │ ftjob-wGoBDld... │ cancelled │ 2023-08-23 │ N/A │ │ file-F7lJg6Z4... │ 3 │ gpt-5.4-mini-... │ │ │ │ 22:44:12 │ │ │ │ │ │ │ ftjob-yd5aRTc... │ ✅ succeeded │ 2023-08-23 │ 2023-08-23 │ ft:gpt-3.5-tur... │ file-IQxAUDqX... │ 3 │ gpt-5.4-mini-... │ │ │ │ 14:26:03 │ 15:02:29 │ │ │ │ │ └────────────────┴──────────────┴────────────────┴────────────────┴─────────────────┴────────────────┴────────┴─────────────────┘ Automatically refreshes every 5 seconds, press CtrlC to exit5.1 表格字段与状态语义从 instructor/cli/jobs.py 的表格生成逻辑看每一行对应一个FineTuningJob对象包含Job ID、状态、创建时间、完成时间、微调后的模型名、训练文件 ID、epochs 数、基础模型。状态通过 emoji 与颜色双重编码源码中定义的映射为状态emoji颜色running⏳yellow黄色succeeded✅green绿色failed❌red红色cancelledwhite默认其他未知状态❓white默认5.2 三个可调选项watch()函数签名揭示了三个隐藏选项instructor/cli/jobs.py--limit监控的任务条数默认5--poll刷新间隔秒默认5--screen是否以全屏模式输出默认关闭。监控逻辑使用rich.live.Live实现启动后每poll秒调用fine_tuning.jobs.list(limitlimit)拉取最新任务、按创建时间倒序排列并重绘表格直到你按CtrlC退出。任务列表按created_at降序排序最新的任务永远出现在顶部。5.3 取消任务jobs cancel当发现训练走向不符合预期如 loss 异常、参数配置错误时可以直接取消$ instructor jobs cancel job_id源码 instructor/cli/jobs.py 中取消通过client.fine_tuning.jobs.cancel(id)完成成功或失败均会在终端以红色日志反馈。六、配套文件管理instructor files微调任务的训练集、验证集本质上都是 OpenAI 平台上的文件instructor files子命令提供了完整的文件生命周期管理instructor/cli/files.py子命令作用instructor files upload filepath上传文件默认purposefine-tune并轮询等待状态变为processedinstructor files list列出服务器上全部文件instructor files status file_id持续监控单个文件的状态pending/processed时退出instructor files download file_id output下载文件到本地指定路径instructor files delete file_id删除服务器上的文件upload命令支持--purpose默认fine-tune与--poll默认 5 秒两个选项上传后同样会阻塞轮询直至文件被处理完成。list命令的输出样例$ instructor files list OpenAI Files ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┓ ┃ File ID ┃ Size (bytes) ┃ Creation Time ┃ Filename ┃ Purpose ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┳━━━━━━━━━━━┩ │ file-0lw2BSNRUlXZXRRu2beCCWjl │ 369523 │ 2023-08-23 23:31:57 │ file │ fine-tune │ │ file-IHaUXcMEykmFUp1kt2puCDEq │ 369523 │ 2023-08-23 23:09:35 │ file │ fine-tune │ │ file-ja9vRBf0FydEOTolaa3BMqES │ 369523 │ 2023-08-23 22:42:29 │ file │ fine-tune │ │ file-F7lJg6Z47CREvmx4kyvyZ6Sn │ 369523 │ 2023-08-23 22:42:03 │ file │ fine-tune │ │ file-YUxqZPyJRl5GJCUTw3cNmA46 │ 369523 │ 2023-08-23 22:29:10 │ file │ fine-tune │ └───────────────────────────────┴──────────────┴─────────────────────┴──────────┴───────────┘文件列表同样按创建时间倒序排列便于快速找到最新上传的数据。七、完整工作流从蒸馏数据到微调上线instructor jobs命令的典型使用场景是配合instructor的**蒸馏distillation**能力先用大模型或规则代码跑出一批高质量样本再用 CLI 上传微调把能力蒸馏进更小、更便宜的模型。7.1 用Instructions生成微调数据集instructor/distil.py 中的Instructions类提供了instructions.distil装饰器可以自动把函数输入 → 结构化输出的调用记录落盘为微调所需的 JSONL。FinetuneFormat枚举支持两种格式MESSAGES对话式 function-call 格式与RAW原始函数调用记录。仓库中的 examples/distilations/three_digit_mul.py 给出了最小可运行示例import logging from pydantic import BaseModel, Field from instructor import Instructions logging.basicConfig(levellogging.INFO) instructions Instructions( namethree_digit_multiply, finetune_formatmessages, log_handlers[logging.FileHandler(math_finetunes.jsonl)], ) class Multiply(BaseModel): a: int b: int result: int Field(..., descriptionThe result of the multiplication) instructions.distil def fn(a: int, b: int) - Multiply: Return the result of multiplying a and b together resp a * b return Multiply(aa, bb, resultresp) if __name__ __main__: import random for _ in range(10): a random.randint(100, 999) b random.randint(100, 999) print(returning, fn(a, bb))运行后会在本地生成math_finetunes.jsonl其中每条记录都包含 system 提示函数签名与 docstring、user 输入如Return fn(169, b166)以及 assistant 的function_call参数含完整的 JSON Schema这正是create-from-file所需的训练数据格式。更多端到端示例可参考 docs/blog/posts/distilation-part1.md 与 examples/chain-of-density/chain_of_density.py后者演示了将 Chain of Density 方法蒸馏进微调模型的完整流程。7.2 数据 → 微调 → 部署的标准流水线结合上文所有命令一个标准的微调流水线如下# 1. 生成训练/验证 JSONL见上述 Python 蒸馏脚本 # 2. 一条命令完成上传 训练推荐 instructor jobs create-from-file math_finetunes.jsonl \ --validation_file math_finetunes_val.jsonl \ --n_epochs 3 \ --batch_size 16 \ --learning_rate_multiplier 0.5 # 3. 或拆分执行先上传文件再从 ID 创建任务 instructor files upload math_finetunes.jsonl instructor files upload math_finetunes_val.jsonl instructor files list instructor jobs create_from_id training_file_id \ --validation_file validation_file_id \ --n_epochs 3 --batch_size 16 --learning_rate_multiplier 0.5 # 4. 监控训练进度每 5 秒自动刷新 instructor jobs list # 5. 训练完成拿到微调模型 ID如 ft:gpt-5.4-mini:my-suffix:xxx后取消任务清理资源 instructor jobs cancel job_id八、注意事项与扩展方向API 覆盖不完整如 docs/cli/finetune.md 明确警告CLI 仍在开发中并未覆盖 OpenAI 微调 API 的全部特性。若某个特性当前不支持可以查阅官方文档或考虑向项目提交贡献。凭据要求除--help外的真实读写操作上传、创建、取消、删除都需要有效的OPENAI_API_KEY否则会抛出OpenAIErrortests/cli/test_help.py 对此有专门测试。轮询行为create-from-file与files upload都会阻塞直到文件状态变为processed才返回超大数据集的上传等待时间较长可适当调大--poll避免频繁请求。低垂的贡献点文档中列出的待办包括上传时补充文件名Adding filenames on upload——当前files list表格中的 Filename 列显示为通用值有兴趣的读者可以以此为切入点参与开发。总结instructor jobs与instructor files构成了一个聚焦、可脚本化的微调管理工具链create-from-file把上传 训练压缩为一步并自动转入监控create-from-id适合已有文件的二次复用jobs list提供秒级刷新的可视化仪表盘files子命令补全了文件上传、下载、删除与状态跟踪。配合 instructor/distil.py 的蒸馏能力你可以用少量 Python 代码完成从数据生成、微调到模型上线的全流程闭环。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考