magika-cli基于 Rust 的深度学习文件类型检测命令行工具完全指南【免费下载链接】magikaFast and accurate AI powered file content types detection项目地址: https://gitcode.com/GitHub_Trending/ma/magikamagika-cli 是 Magika 项目的 Rust 命令行前端它构建在同仓库的magika库 crate 之上通过 ONNX Runtime 加载深度学习模型来判定文件的真实内容类型而不是依赖扩展名或简单的魔数。本文基于仓库中 rust/cli/README.md 的完整内容并结合 CLI 入口源码、库 crate 实现 与 输出格式文档系统讲解它的安装方式、全部命令行参数、JSON/JSONL/自定义格式输出以及底层特征提取—批量推理—结果重排的并行流水线设计读完即可在实际项目中安全地将其用于批量文件审计与自动化内容分类。magika-cli 是什么二进制 crate 与库 crate 的分工按照 rust/cli/README.md 的定义magika-cli是一个 binary crate它把 magika 库 crate提供深度学习文件类型检测能力封装成名为magika的可执行程序。从 rust/README.md 可以确认整个 Rust 工作区的布局cli/Magika 的 Rust CLI发布到 crates.io 的包名为magika-cli在cli目录下执行cargo build --release后可得到target/release/magika二进制文件lib/magika库 crateCLI 依赖它完成特征提取与模型推理gen/维护者在发布新模型时使用的代码生成 cratesync.sh在有新模型时利用gencrate 更新库test.sh负责测试各 crate 并纳入 CI。从依赖声明看rust/cli/Cargo.tomlCLI 直接依赖本地路径的magika库path ../lib开启serdefeature、ortONNX Runtime 绑定、tokio异步运行时、clap参数解析与colored终端着色。当前仓库中 CLI 的版本为0.1.0-rc.3-dev。稳定性声明与原文档一致安装前务必了解该项目不是 Google 官方项目不受 Google 支持magika库与magika-cli均处于不稳定状态主版本号为 0新版本可能引入破坏性变更所有变更遵循 cargo semver 兼容规则0.1.0-rc.0相比 Python 版二进制携带了一个新模型从 rust/cli/CHANGELOG.md 看rc.1 起模型已从standard_v2_0切换到standard_v2_1官方希望社区在 GitHub 上反馈问题。安装方式magika-cli提供了三种安装途径均已在 rust/cli/README.md 中给出1. 从 crates.io 安装最新版推荐cargo install --locked magika-cli2. 从 git 仓库安装cargo install --locked --githttps://github.com/google/magika.git magika-cli此时执行magika --version看到的版本号会带-dev后缀例如0.1.0-dev表示这是某版本前缀如0.1.0的开发版二进制。3. 从本地克隆的仓库安装可能包含自定义修改git clone https://github.com/google/magika.git cd magika cargo install --locked --pathrust/cli值得注意的是--version的输出并不只是二进制版本。从 rust/cli/src/main.rs 可以看到版本号由crate_version!()与magika::MODEL_NAME拼接而成即会同时打印所搭载的深度学习模型名称——这与 CHANGELOG 中 rc.1 Print model version with--version 的条目相互印证方便用户区分不同模型版本的输出差异。基本用法示例以下示例均继承自原文档可直接在克隆本仓库后验证仓库自带 tests_data/basic 测试语料递归识别一个目录中的所有文件$ cd tests_data/basic magika -r * asm/code.asm: Assembly (code) batch/simple.bat: DOS batch file (code) c/code.c: C source (code) css/code.css: CSS source (code) csv/magika_test.csv: CSV document (code) dockerfile/Dockerfile: Dockerfile (code) docx/doc.docx: Microsoft Word 2007 document (document) epub/doc.epub: EPUB document (document) flac/test.flac: FLAC audio bitstream data (audio) html/doc.html: HTML document (code) jpeg/magika_test.jpg: JPEG image data (image) json/doc.json: JSON document (code) markdown/README.md: Markdown document (text) [...]默认的每行格式是路径: 描述 (分组)括号内的分组code、document、audio、image、text 等来自内容类型知识库。输出机器可读的 JSON$ magika ./tests_data/basic/python/code.py --json [ { path: ./tests_data/basic/python/code.py, result: { status: ok, value: { dl: { description: Python source, extensions: [py, pyi], group: code, is_text: true, label: python, mime_type: text/x-python }, output: { description: Python source, extensions: [py, pyi], group: code, is_text: true, label: python, mime_type: text/x-python }, score: 0.753000020980835 } } } ]从标准输入读取内容路径参数使用单独的-且只能出现一次$ cat doc.ini | magika - -: INI configuration file (text)仓库中还保存了一份 CLI 实际运行的输出快照 rust/cli/output其中可以看到--colors、--output-score、--json、--jsonl、--mime-type等参数在真实运行中的输出样例可作为回归测试的参考基准。完整命令行参数说明以下是magika --help的完整参数清单继承自原文档与 main.rs 中的 Flags 定义 一致Determines the content type of files with deep-learning Usage: magika [OPTIONS] [PATH]... Arguments: [PATH]... List of paths to the files to analyze. Use a dash (-) to read from standard input (can only be used once). Options: -r, --recursive Identifies files within directories instead of identifying the directory itself --no-dereference Identifies symbolic links as is instead of identifying their content by following them --colors Prints with colors regardless of terminal support --no-colors Prints without colors regardless of terminal support -s, --output-score Prints the prediction score in addition to the content type -i, --mime-type Prints the MIME type instead of the content type description -l, --label Prints a simple label instead of the content type description --json Prints in JSON format --jsonl Prints in JSONL format --format CUSTOM Prints using a custom format (use --help for details). The following placeholders are supported: %p The file path %l The unique label identifying the content type %d The description of the content type %g The group of the content type %m The MIME type of the content type %e Possible file extensions for the content type %s The score of the content type for the file %S The score of the content type for the file in percent %b The model output if overruled (empty otherwise) %% A literal % -h, --help Print help (see a summary with -h) -V, --version Print version参数之间的约束关系在源码中有明确体现见 Flags 结构体 的 clap 分组标注--colors与--no-colors互斥#[group(multiple false)]--mime-type与--label互斥且二者作为修饰符与--format整组冲突#[group(conflicts_with format)]——使用--format时请用占位符而不是修饰符--json、--jsonl、--format三者互斥#[group(id format, multiple false)]标准输入的-最多出现一次违反会直接报错only one path can be the standard input。除上述公开参数外源码中还有一个Experimental参数组全部以hide true隐藏不显示在 help 中但确实存在并可调优性能隐藏参数说明默认值--batch-size单次推理包含的文件数1不允许为 0--num-tasks批量并行推理的任务数CPU 核数--inter-threadsONNX Runtime 图并行线程数不设置--intra-threadsONNX Runtime 节点并行线程数macOS 下默认 4--optimization-levelONNX Runtime 图优化级别取值 0–3不设置--parallel-execution是否启用 ONNX Runtime 并行执行不设置其中 macOS 的--intra-threads默认值为 4 是有意为之build_session 中的注释 指出在 macOS 上若不显式调用SetIntraOpNumThreadsRunAsync会报 intra op thread pool must have at least one thread 错误这条修复同样记录在 CHANGELOG 的 rc.1 条目中。自定义输出格式--format占位符体系--format CUSTOM允许完全控制输出模板。占位符全集如下继承自原文档 help 文本占位符含义%p文件路径%l标识内容类型的唯一 label%d内容类型的人类可读描述%g内容类型的高层分组%mMIME 类型%e该类型常见的文件扩展名列表%s预测得分如0.75源码中按两位小数截断%S以百分比显示的得分如75%向下取整%b当规则结果覆盖了模型输出时显示模型的最佳猜测及其得分否则为空%%字面量%从 Response::format 的实现 可以看到不指定--format/--json/--jsonl时CLI 实际使用的等效模板是按修饰符拼装出来的基础模板为%p:其后跟随%m--mime-type、%l--label或默认%d (%g)再追加%b被规则覆盖时的低置信度提示若加了-s/--output-score则再追加%S。这也解释了为什么示例中magika rust/code.rs --output-score会输出rust/code.rs: Rust source (code) 99%见 rust/cli/output。%b对应的场景是当模型置信度过低、最终结论由规则层兜底如Generic text document时输出中会附注[Low-confidence model best-guess: ...]便于调试。输出格式详解dl、output与score的语义--json/--jsonl的输出结构与 Magika 各语言 APIPython、JS、Rust保持一致权威解释见 docs/magika_output.md。结合上文的 Python 示例字段含义为path本次预测对应的文件路径多文件扫描时有意义result.status是否为ok。为ok时带value明细失败时其值会被序列化为具体错误枚举。从 JsonError 定义 看Rust CLI 会区分file_does_not_exist、permission_error与兜底的unknown三类score预测置信度0–1 浮点数dl块深度学习模型的原始预测本例中模型判定为pythonoutput块Magika 这个工具的最终预测它综合了模型预测、置信度等因素。当模型置信度足够高时output与dl一致置信度低时output会退化为通用类型如 Generic text document 或 Unknown binary data两个块内的元数据字段包括label适合自动化处理的唯一标签、description人类可读描述、mime_type、extensions、group以及is_text布尔值文本型还是二进制型。文档同时给出两条重要边界事实多数客户端应直接使用output.labeldl主要用于调试并非所有情况都会走到模型文件过小当前阈值为小于 16 字节时不会调用深度学习模型此时dl块的 label 为未定义值。这一点与 Rust 库的设计一致——FeaturesOrRuled 枚举 就区分了需要提取特征走模型Features与直接规则判定Ruled两条路径此外 main.rs 的 process_path 显示目录非递归时判为Directory与符号链接--no-dereference时同样走规则路径不消耗任何推理开销。退出码与错误处理从 CHANGELOG 看rc.2 起只要遇到至少一个错误就以非零码退出修复 issue #780。对应到源码main 函数末尾 在收集所有响应后检查errors标志并调用std::process::exit(1)。这意味着在 CI 或 shell 管道中可以用$?可靠地感知扫描失败而单条记录级别的错误仍会以正常行终端下为红色加粗见 color 实现或 JSON 的status字段呈现不会中断其余文件的输出。源码纵深特征提取、批量推理与结果重排的并行流水线CLI 之所以能同时处理成百上千个文件并保持输出顺序与输入一致靠的是 main 函数中的三通道 tokio 流水线特征提取生产者extract_features任务按输入顺序遍历路径-会先把整个 stdin 读入内存再提取特征process_path-r时遇到目录会read_dir并把子项按排序后倒序压栈从而以字典序逐个入队这解释了示例中tests_data/basic的输出顺序每攒够--batch-size个特征就通过async_channel::bounded(num_tasks)发送一个BatchL232-L264推理消费者num_tasks个任务默认等于 CPU 核数每个任务循环接收Batch调用库的identify_features_batch_async——该函数把批内特征拼成[batch, features_size]的二维张量一次性喂给 ONNX session读取target_label输出张量后转换为FileTypesession.rs结果重排器Reorder结构由于多任务并行推理结果返回顺序是乱的每个Response携带入队序号orderReorder用 HashMap 暂存乱序结果pop时严格按order递增吐出L360-L382。这保证了--json数组元素顺序与命令行参数顺序严格一致——对下游按位置解析的脚本很关键。JSON 模式下的输出也是流式的开头打印[每条记录用缩进的 pretty JSON 拼接L198-L225--jsonl则是每条记录一行紧凑 JSON见 rust/cli/output 中的 jsonl 样例适合| while read这类流式处理场景。测试与验证途径rust/cli/test.sh与根级 rust/test.sh 会驱动 CLI 对测试语料跑参数矩阵并与 rust/cli/output 中的参考快照比对rust/README.md说明该脚本也运行在 GitHub CI 中若只需手工验证克隆仓库后在任意子目录执行magika tests_data/basic/python/code.py --json即可复现上文的完整 JSON 样例库 crate 侧的行为如同步/异步识别、从内存字节识别内容可参考 rust/lib/src/lib.rs 顶部文档示例例如identify_content_sync(b#!/bin/sh\necho hello[..])应得到shelllabel。小结magika-cli 用一个简洁的参数面覆盖了文件类型检测的主要使用场景路径/目录/stdin 三种输入源、--json/--jsonl/--format三种机器可读输出、-i/-l/-s修饰符与彩色终端输出底层则由特征提取、批量 ONNX 推理与乱序重排组成的并行流水线支撑并通过dl/output双块输出透明地暴露模型预测与工具最终裁决的差异。由于项目仍处于 0.x 不稳定阶段且各版本携带的模型可能不同当前仓库为 rc.3-dev模型standard_v2_1在自动化流程中固定版本、以output.label作为主要判据是原文档与源码共同指向的稳妥用法。【免费下载链接】magikaFast and accurate AI powered file content types detection项目地址: https://gitcode.com/GitHub_Trending/ma/magika创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考