3.3 CLI 工具

3.3 CLI 工具

本节摘要：不写 Python 也能用 laya：官方 CLI 覆盖命令行预测、脚本检测与模型信息查看三类能力（能力清单为官方口径，具体子命令与参数以官方仓库 README 为准，本章命令一律标写法示意）。本节先给 CLI 的能力全景与「先看帮助」的习惯，再逐个过三类命令：预测（把一段文本问成 choice / score / noul）、脚本检测（看 Router 会怎么分流）、模型信息（检查点参数量与语言覆盖）；然后把 CLI 接进 shell 管道——cat 喂文本、输出接 jq 或后续脚本，laya 就成了可以组合的 Unix 工具；最后划清 CLI 与 SDK 的边界：CLI 管人工验证与脚本胶水，SDK 管应用内集成，服务化（第 4 章）管跨系统调用。

学习目标

• 用 CLI 完成一次命令行预测、一次脚本检测、一次模型信息查看。
• 把 CLI 接进 shell 管道，做成可组合的文本处理环节。
• 说出 CLI、SDK、laya-serve 三种入口各自的边界。
• 养成「先看帮助、再抄示例」的 CLI 使用习惯。

一、CLI 全景

安装 laya 包后，命令行入口即随包提供（具体命令名与子命令以官方仓库 README 为准）。能力分三类：预测（对文本问一个 typed 问题）、脚本检测（看一段文本会触发什么路由）、模型信息（看检查点的家底）。写法示意如下：

# bash —— CLI 能力速览（写法示意，子命令与参数以官方仓库 README 为准）
laya --help                    # 第一个习惯：先看帮助再动手
laya predict --help            # 预测子命令的参数说明
​

用 CLI 的两条纪律。第一，把它当快车道不当替代品：CLI 适合「我现在就想知道这段文本会被判成什么」，不适合「我的服务要每秒判一千次」。第二，帮助文档优先于任何教程（包括本书）：laya 迭代快，参数名变了时 --help 的输出永远比教材新。

还有一条容易被忽略的纪律：CLI 的版本跟着包走。pip 装的 laya 升级后，子命令的行为可能变化——在共享给团队的脚本里用 CLI 时，把「laya 版本号」写进脚本注释或打印出来（写法示意：pip show laya），否则半年后「脚本怎么不工作了」的排查会从玄学开始。

二、命令行预测

# bash —— 命令行预测（写法示意）
laya predict \
  --text "客户邮件：订单三天未发货，客服电话打不通。" \
  --question "这封邮件属于哪个类别？" \
  --options "物流投诉,产品咨询,营销推广,其他" \
  --type choice
​

预期输出形态（示意值）：

# cli_predict_output.txt —— 输出示意
answer:      物流投诉
confidence:  0.57
probabilities:
  物流投诉  0.57
  产品咨询  0.22
  营销推广  0.09
  其他      0.12
checkpoint:  laya-multilingual
​

与 SDK 的返回逐字段对得上——这不是巧合，CLI 与 SDK 是同一能力的两个皮。学会任何一个，另一个的输出都能直接读懂；反过来，用 CLI 复现某个 SDK 调用的行为，是排障时最快的交叉验证手段。

CLI 预测的典型用途有三个：写代码前快速验证「这个问题 laya 接得住吗」；调试问题时复现某个具体输入的行为（拿到与 SDK 相同的 checkpoint 归属，方便对比）；给非工程同事演示能力——一行命令胜过一段代码。noul 与 score 同理，换 --type 与问题措辞即可（参数以 --help 为准）。

配合机器可读输出（参数写法示意），CLI 就能直接喂下游脚本：加一个 JSON 输出开关，预测结果变成一行一个 JSON 对象，jq、Python 一行流都能接。

# bash —— 机器可读输出（写法示意，参数以 --help 为准）
laya predict --text "..." --question "..." --type noul --json
# 输出一行 JSON：answer / confidence / checkpoint 字段与 SDK 同构
​

三、脚本检测与模型信息

# bash —— 脚本检测与模型信息（写法示意）
laya detect-script --text "这是一段中文与 English 混合的文本"
# 预期：给出检测到的书写系统（具体输出格式以实测为准）

laya info
# 预期：列出可用检查点、参数量、语言覆盖（以实测为准）
​

脚本检测命令的价值在第 2.3 节的混合语言实测里最明显：把拿不准的样本批量喂给检测命令，先看 Router 的「前置判断」，再对照 predict 的 checkpoint 字段，两步就能确认「检测与分流是否一致」。模型信息命令则是第 2.1 节那张对比表的活数据源——本地到底装了哪些检查点、各覆盖什么，以它为准而不是以教材为准。

CLI 与 SDK 还共享同一份模型缓存与配置：CLI 试过的检查点已经下载好了，SDK 直接用；反过来也一样。这让「先用 CLI 敲一行验证想法、再落成 SDK 代码」的工作流零成本切换——两边看到的是同一台机器的同一个状态。

四、管道化用法

CLI 的真正威力在管道。文本从标准输入进、结果往标准输出走，laya 就成了 Unix 哲学里的一个普通过滤器：

# bash —— 管道化用法（写法示意）
# 用法一：文件喂入
cat tickets.txt | laya predict \
  --question "属于哪个类别？" \
  --options "账务,软件缺陷,售前咨询,物流" \
  --type choice

# 用法二：预测结果接后续处理（ jq 换行解析字段，示例为思路示意）
cat mixed_input.txt | laya predict --question "..." --type noul | grep "answer"

# 用法三：先检测脚本再预测，两段管道各司其职
cat stream.txt | laya detect-script | laya predict --question "..."
​

管道化的适用场景：存量文本文件的一次性清洗（配合 awk 或 cut 做字段抽取）；定时任务里的夜间批处理（cron 调一段 shell，不必写 Python）；数据探查（抽样看一批真实输入会被判成什么，为第 2.3 节的路由实测与第 5 章的微调数据准备服务）。注意管道里每次调用都是独立进程，吞吐不如第 3.2 节的 predict_batch——管道图的是组合方便，不是性能。

三个可以直接抄走改造的管道配方（写法示意）：

管道里的错误处理也要想好：某一行预测失败时，是中断整条管道还是跳过并记日志？数据探查场景跳过即可（配方一、二），正式清洗场景必须中断（防止静默丢数据）——同一个工具在不同配方里的失败策略不同，这是写脚本前要想清楚的一分钟。

三条实现细节（示意建议）：长输入先截断或过滤（超长行会拖慢整条管道，处理策略见第 6 章）；输出统一编码（UTF-8 一以贯之，避免 Windows 与 Linux 管道间的乱码）；管道里别用交互式参数（任何需要确认的开关都会卡死整条链）。

五、CLI 与 SDK 的边界

这张表在团队协作里还有一层用法：把它贴在决策服务的文档首页，新人接手时先对「我要做什么」再对「我用哪个入口」，能挡掉大半「为什么不给我 HTTP 接口」式的沟通成本。入口选择是使用文档的第一行，不是附录。

三条边界的判据是「谁在调用」：人敲命令用 CLI，Python 代码用 SDK，别的系统（Go 服务、前端网关、另一个团队的脚本）用 HTTP 服务。常见反模式是拿 CLI 当服务用（shell 循环调 CLI 处理在线流量），进程启动开销会把延迟放大一个量级——在线流量请等下一章的 laya-serve。反过来也有一个温和的反模式：明明是人在做一次性分析，却非要起个 Python 工程写批量脚本——一条管道十分钟出结果的事，不值得一下午的工程化。工具选小了伤性能，选大了伤自己。

本节要点回顾

• CLI 三类能力：预测、脚本检测、模型信息；先看 --help 再抄示例是纪律。
• 预测命令的输出与 SDK 同构（answer、confidence、probabilities、checkpoint），可互相印证。
• 管道化让 laya 成为 Unix 过滤器：适合一次性清洗、cron 批处理、数据探查；吞吐不如 predict_batch。
• 三个配方可直接抄改：夜间清洗、抽样探查、两段路由；失败策略按场景选中断或跳过。
• 边界判据「谁在调用」：人用 CLI、代码用 SDK、系统用 serve；别拿 CLI 当服务。

至此 SDK 与 CLI 都通了，但它们都要求调用方在你的机器上、用你的运行时。下一章把能力搬到线上：laya-serve 以 HTTP 服务的形式暴露同一套决策能力，并且与 Jev 同线协议——官方客户端改个 baseUrl 就能直连。