Instructor 命令行工具完全指南usage / jobs / batch / docs 全命令实战解析【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructorInstructor 不仅是结构化输出的 Python 库还内置了一套开箱即用的命令行工具CLI让你可以在终端中直接完成 OpenAI API 用量监控、微调任务管理、批量任务调度与文档检索。本篇指南以 docs/cli/index.md 为主线结合仓库中 instructor/cli/ 的源码实现系统讲解每个子命令的参数、输出形态与底层原理读完后你可以在自己的项目中直接上手使用instructor usage、instructor jobs、instructor batch与instructor docs四组命令。快速开始安装与配置CLI 工具随 Instructor 包一起发布无需单独安装pip install instructor安装完成后pyproject.toml中的[project.scripts]声明会注册instructor命令入口指向 instructor/cli/cli.py 中的 Typer 应用见 pyproject.toml[project.scripts] instructor instructor.cli.cli:app使用与 OpenAI 相关的命令前需要先配置 API Keyexport OPENAI_API_KEYyour-api-key-here如果使用 Anthropic 提供商的批量功能还需设置export ANTHROPIC_API_KEYyour-anthropic-api-key从源码看instructor/cli/cli.py 通过typer.Typer()注册了五个子命令组其中hub已标记为[DEPRECATED]The instructor hub is no longer available实际可用的命令组为命令功能对应文档instructor usage查询 OpenAI API 用量与成本docs/cli/usage.mdinstructor jobs创建与管理微调任务docs/cli/finetune.mdinstructor files管理 OpenAI 服务器上的文件docs/cli/finetune.mdinstructor batch多提供商批量任务管理docs/cli/batch.mdinstructor docs在浏览器中打开文档见下文文档命令另外docs/cli/index.md 中提到的fine-tune入口在真实 CLI 中以jobs命令组的形式存在instructor finetune并非实际注册的命令名具体以instructor jobs为准实现位于 instructor/cli/jobs.py。Usage 命令终端里的 API 用量监控instructor usage用于监控 OpenAI API 的用量数据并按模型、日期与成本维度进行拆分展示。查看帮助$ instructor usage --help Usage: instructor usage [OPTIONS] COMMAND [ARGS]... Check OpenAI API usage data ╭─ Options ───────────────────────────────────────────────────────╮ │ --help Show this message and exit. │ ╰─────────────────────────────────────────────────────────────────╯ ╭─ Commands ──────────────────────────────────────────────────────╮ │ list Displays OpenAI API usage data for the past N days. │ ╰─────────────────────────────────────────────────────────────────╯usage组下只有一个子命令list支持通过--n指定查询最近多少天的数据。查询最近 N 天用量$ instructor usage list --n 3输出为一张 Rich 表格按日期、快照模型分组汇总请求数与成本Usage Summary by Date, Snapshot, and Cost ┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓ ┃ Date ┃ Snapshot ID ┃ Total Requests ┃ Total Cost ($) ┃ ┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩ │ 2023-09-04 │ gpt-5.4-mini │ 44 │ 0.68 │ │ 2023-09-04 │ gpt-5.4-mini │ 195 │ 0.84 │ │ 2023-09-04 │ text-embedding-ada-002-v2 │ 276 │ 0.00 │ │ 2023-09-04 │ gpt-4-32k-0613 │ 328 │ 49.45 │ └────────────┴───────────────────────────┴────────────────┴────────────────┘查询今天的用量不传任何参数时instructor usage list默认只取当天n0的数据。$ instructor usage list源码层面的实现原理instructor/cli/usage.py 的实现值得关注它揭示了这个命令的三层工作原理异步抓取fetch_usage(date)使用aiohttp并发请求https://api.openai.com/v1/usage?date{date}usage.pyget_usage_for_past_n_days通过asyncio.gather并行拉取多天数据并用 RichProgress显示进度条usage.py。静态价格表成本计算依赖MODEL_COSTS这一内置静态价格表覆盖 gpt-4o、gpt-4-turbo、gpt-3.5-turbo 系列及 text-embedding 系列等模型usage.py。get_model_cost对未知模型名做前缀回退匹配例如以gpt-3.5-turbo开头的模型会回退到对应系列的基准价格usage.py。分组汇总group_and_sum_by_date_and_snapshot按日期和 snapshot_id 聚合请求数、token 数与成本按日期倒序渲染成 Rich 表格usage.py。重要限制见 docs/cli/usage.md 的警告该命令基于旧版 OpenAI usage 端点与静态价格表不与账单对账也未考虑当前的缓存、工具调用、多模态、批量任务或服务等级定价模型前缀回退可能对更新的模型变体套用错误费率空结果也不代表零用量。因此它只适合日常粗粒度监控财务报告请以提供商账单为准。Files 命令管理服务器上的文件instructor files是微调流程的配套工具负责管理上传到 OpenAI 服务器的文件实现位于 instructor/cli/files.py$ instructor files --helpinstructor files upload filepath上传文件默认purpose为fine-tune并轮询默认 5 秒直至状态变为processed才返回files.pyinstructor files download file_id output下载指定文件到本地files.pyinstructor files delete file_id从服务器删除文件files.pyinstructor files status file_id持续监控文件处理状态遇到pending或processed状态即停止files.pyinstructor files list列出所有文件按创建时间倒序展示文件 ID、大小字节、创建时间、文件名与用途files.py。Jobs 命令创建与管理微调任务instructor jobs提供在 OpenAI 上管理微调任务的完整能力。需要注意的是docs/cli/finetune.md 明确指出该 CLI 仍在开发中尚未覆盖 API 的全部特性。查看帮助$ instructor jobs --help Usage: instructor jobs [OPTIONS] COMMAND [ARGS]... Monitor and create fine tuning jobs ╭─ 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. │ ╰─────────────────────────────────────────────────────────────────╯从文件创建微调任务create-from-filecreate-from-file把上传训练文件 启动微调合并为一步先上传文件并等待处理完成再创建微调任务实现见 jobs.py$ instructor jobs create-from-file transformed_data.jsonl \ --validation_file validation_data.jsonl \ --n_epochs 3 \ --batch_size 16 \ --learning_rate_multiplier 0.5完整参数说明参数类型默认值说明file位置参数TEXT必填用于微调的训练文件路径--modelTEXTgpt-5.4-mini微调使用的基座模型--pollINTEGER2轮询间隔秒--n-epochsINTEGER无微调轮数--batch-sizeINTEGER无微调批次大小--learning-rate-multiplierFLOAT无学习率倍率--validation-fileTEXT无验证集文件路径--model-suffixTEXT无用于标识微调后模型的名称后缀源码中未指定的超参数不会进入hyperparameters字典jobs.py训练文件与验证文件都会以purposefine-tune上传并轮询文件状态直到processed才继续创建任务jobs.py。从已上传文件 ID 创建create-from-id如果文件已上传过可以用create-from-id直接引用文件 ID 创建任务$ 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关键参数id位置参数已上传训练文件 ID、--model默认gpt-5.4-mini、--validation-file-id、以及三个可选超参数--n-epochs/--batch-size/--learning-rate-multiplier见 jobs.py。监控任务状态list与取消cancel$ instructor jobs listjobs list默认监控最近 5 个任务输出 Rich 实时表格每 5 秒自动刷新一次按CtrlC退出OpenAI Fine Tuning Job Monitoring ┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━┓ ┃ Job ID ┃ Status ┃ Creation Time ┃ Completion Time┃ Model Name ┃ File ID ┃ Epochs ┃ Base Model ┃ ┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━┩ │ ftjob-PWo6uwk... │ cancelled │ 2023-08-23 │ N/A │ │ file-F7lJg6Z4... │ 3 │ gpt-5.4-mini-... │ │ ftjob-yd5aRTc... │ ✅ succeeded │ 2023-08-23 │ 2023-08-23 │ ft:gpt-3.5-tur... │ file-IQxAUDqX... │ 3 │ gpt-5.4-mini-... │ └────────────────┴──────────────┴────────────────┴─────────────────┴─────────────────┴────────────────┴────────┴─────────────────┘ Automatically refreshes every 5 seconds, press CtrlC to exit状态列通过 emoji 与颜色区分⏳ running黄色、✅ succeeded绿色、❌ failed红色、 cancelled见 jobs.py。jobs list还支持--limit监控数量与--poll刷新间隔参数。取消任务$ instructor jobs cancel job_idBatch 命令多提供商统一批量任务管理instructor batch通过统一接口管理 OpenAI 与 Anthropic 两个提供商的批量任务所有命令共用--provider标志默认openai并向后兼容旧的--use-anthropic标志使用时会给出弃用警告。底层实现全部委托给 instructor/batch/processor.py 中的BatchProcessor其抽象接口定义在 instructor/batch/providers/base.py。$ instructor batch --help Usage: instructor batch [OPTIONS] COMMAND [ARGS]... Manage OpenAI Batch jobs ╭─ Commands ───────────────────────────────────────────────────────╮ │ cancel Cancel a batch job │ │ create Create batch job using BatchProcessor │ │ create-from-file Create a batch job from a file │ │ delete Delete a completed batch job │ │ download-file Download the file associated with a batch job │ │ list See all existing batch jobs │ │ results Retrieve results from a batch job │ ╰──────────────────────────────────────────────────────────────────╯列出批量任务list$ instructor batch list --provider openai --limit 3list的关键选项见 batch.py选项默认值说明--limit10展示的批量任务数量--poll10轮询间隔秒--screen/--no-screenno-screen是否启用全屏输出--live/--no-liveno-live是否实时轮询刷新表格--provideropenai提供商如openai、anthropic--full-idFalse是否显示完整 Batch ID默认截断为 15 字符加...--use-anthropic已弃用no-use-anthropic旧标志改用--provider anthropic表格会根据提供商展示不同的状态列OpenAI 显示 Completed / Failed / TotalAnthropic 显示 Succeeded / Errored / Processing状态颜色编码为pending黄、processing蓝、completed绿、failed/cancelled/expired红batch.py。时长由started_at与completed_at之差自动计算不足 60 分钟以m为单位否则以h为单位。Openai Batch Jobs ┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━┓ ┃ Batch ID ┃ Status ┃ Created ┃ Started ┃ Duration┃ Completed┃ Failed ┃ Total ┃ ┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━┩ │ batch_abc123... │ completed │ 07/07 23:48│ 07/07 23:48│ 2m │ 15 │ 0 │ 15 │ │ batch_def456... │ processing │ 07/07 22:30│ 07/07 22:31│ 45m │ 8 │ 0 │ 10 │ │ batch_ghi789... │ failed │ 07/07 21:15│ N/A │ N/A │ 0 │ 5 │ 5 │ └────────────────────┴────────────┴────────────┴────────────┴─────────┴──────────┴────────┴───────┘从文件创建批量任务create-from-file$ instructor batch create-from-file \ --file-path batch_requests.jsonl \ --model openai/gpt-5-nano \ --description Email classification batch - production v2.1 \ --completion-window 24h参数说明batch.py--file-path必填包含批量请求的.jsonl文件--modelprovider/model-name格式的模型默认openai/gpt-4o-mini如anthropic/claude-3-5-sonnet-20241022--description批量任务的描述/元数据默认Instructor batch job--completion-window完成窗口仅 OpenAI默认24h--use-anthropic已弃用改用--model指定。任务提交后会调用BatchProcessor.submit_batchprocessor.py随后自动展示最新 5 个任务的列表。要生成.jsonl批量请求文件可以使用BatchProcessor.create_batch_from_messages完整示例见 docs/cli/batch.mdfrom instructor.batch import BatchProcessor from pydantic import BaseModel, Field from typing import Literal class Classification(BaseModel): label: Literal[SPAM, NOT_SPAM] Field( ..., descriptionWhether the email is spam or not ) # 创建处理器 processor BatchProcessor(openai/gpt-5-nano, Classification) # 准备消息对话 messages_list [ [ {role: system, content: Classify the following email}, {role: user, content: Hello there Im a Nigerian prince and I want to give you money} ], [ {role: system, content: Classify the following email}, {role: user, content: Meeting with Thomas has been set at Friday next week} ] ] # 生成批量请求文件 processor.create_batch_from_messages( messages_listmessages_list, file_pathbatch_requests.jsonl, max_tokens100, temperature0.1 )此外instructor batch create可以直接从一个包含消息的 JSONL 文件生成批量请求文件通过--response-model指定响应模型的 Python 类路径如examples.User内部会动态导入该模型batch.py。取消、删除与结果获取取消任务两个提供商均支持instructor batch cancel --batch-id batch_abc123 --provider openai instructor batch cancel --batch-id msgbatch_def456 --provider anthropic删除已完成的批量任务仅 Anthropic 支持OpenAI API 不支持删除instructor batch delete --batch-id msgbatch_abc123 --provider anthropic获取结构化结果两个提供商均支持内部通过client.batches.retrieve获取output_file_id再下载或调用 Anthropic 的batches.results迭代器instructor batch results \ --batch-id batch_abc123 \ --output-file openai_results.jsonl \ --model openai/gpt-5-nano旧版download-file命令仍保留用于兼容要求任务必须已completedAnthropic 侧为processing_status ended才能下载原始结果文件batch.py。提供商支持矩阵操作OpenAIAnthropicList✅ 增强表格✅ 增强表格Create✅ 支持元数据✅ 基于文件Cancel✅ 标准 API✅ 标准 APIDelete❌ 不支持✅ 标准 APIResults✅ 结构化解析✅ 结构化解析文档命令终端直达文档instructor docs命令会在默认浏览器中打开 Instructor 官方文档实现在 instructor/cli/cli.py# 打开主文档 instructor docs # 搜索特定主题附带 ?q 查询参数 instructor docs validation # 打开指定页面 instructor docs concepts/models从源码看该命令通过 Typer 的launch在浏览器中打开https://python.useinstructor.com/带查询参数时追加?q{query}。由于 CLI 模块与docs/目录同在一个仓库中也可以直接阅读 docs/index.md 或 docs/concepts/index.md 获取完整的概念体系。小结Instructor CLI 的设计哲学是对 API 提供轻量封装而非完整 CLI见 docs/cli/usage.md 与 docs/cli/finetune.md 的贡献说明。它通过 instructor/cli/cli.py 将usage、jobs、files、batch、docs五组命令聚合到单一入口用 Typer Rich 提供了带颜色、状态 emoji 与自动刷新的终端体验并借助BatchProcessor实现了 OpenAI / Anthropic 的统一批量接口。对于日常开发而言instructor usage list --n 7可以快速掌握近一周的 API 花费instructor jobs create-from-file一行即可拉起微调流程而instructor batch则让大规模批量任务的多提供商调度变得一致、可监控、可回滚。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考