📦 Magika 详细部署教程

Magika 是 Google 开源的一款基于 AI 的文件类型检测工具，它利用深度学习模型实现快速、准确的文件识别。Magika 在约 1 亿个样本、超过 200 种内容类型的数据集上训练，平均准确率约 99%。它支持命令行、Python、JavaScript 等多种使用方式。

⚙️ 部署前准备

Magika 的部署非常简单，根据你选择的使用方式，只需满足相应环境即可。

命令行工具 (CLI)：支持 Rust 环境（从源码编译）或 Python 环境（通过 pip 安装）。
Python API：需要 Python 3.8 或更高版本。
JavaScript API：需要 Node.js 环境。
核心优势：Magika 模型文件仅几 MB，推理速度极快（约 5ms/文件），且与文件大小无关（仅读取文件头部部分字节）。

🚀 安装与使用

Magika 提供了多种安装途径，以适应不同的开发和使用场景。

方式一：命令行工具 (CLI) 安装

这是最直接的使用方式，安装后即可在终端中识别文件。

1. 通过 Python 包安装 (推荐，最通用)
使用 pipx 可以在隔离环境中安装，避免依赖冲突：

1	pipx install magika

备选：也可以使用 pip install magika，但推荐 pipx。
安装后：直接运行 magika <文件路径> 即可。

2. 通过 Homebrew 安装 (macOS / Linux)

1	brew install magika

3. 通过官方安装脚本 (跨平台)

Linux / macOS:

1	curl -LsSf https://securityresearch.google/magika/install.sh \| sh

Windows (PowerShell):

1	powershell -ExecutionPolicy Bypass -c "irm https://securityresearch.google/magika/install.ps1 \| iex"

4. 通过 Rust 包管理器 (cargo) 编译安装
适合 Rust 开发者，需先安装 Rust 工具链：

1	cargo install --locked magika-cli

快速使用 CLI

# 识别单个文件
magika myfile.pdf

# 递归识别目录下所有文件
magika -r ./my_folder/

# 输出为 JSON 格式
magika myfile.docx --json

# 从标准输入读取 (例如通过管道)
cat myfile.py | magika -

方式二：Python API 集成

如果你需要在 Python 项目中使用 Magika，可以将其作为库导入。

1. 安装 Python 包

1	pip install magika

2. 在代码中使用

from magika import Magika

# 创建 Magika 实例 (首次运行会自动下载模型)
m = Magika()

# 识别字节流
res = m.identify_bytes(b'function log(msg) {console.log(msg);}')
print(res.output.label)  # 输出: javascript

# 识别文件
res = m.identify_path('./my_file.csv')
print(res.output.label)  # 输出: csv

# 识别文件流 (适用于大文件)
with open('./my_file.pdf', 'rb') as f:
    res = m.identify_stream(f)
    print(res.output.mime_type)  # 输出: application/pdf

方式三：JavaScript / TypeScript API

Magika 也提供了实验性的 npm 包，适合在 Node.js 或浏览器环境中使用。

1. 安装 npm 包

1	npm install magika

2. 在 Node.js 中使用

import { identify } from 'magika';

const result = await identify(new Uint8Array([0x25, 0x50, 0x44, 0x46]));
console.log(result); // 输出识别结果

注意：JavaScript 版本目前仍在积极开发中，具体 API 请参考官方文档。

🔧 进阶配置与核心概念

预测模式 (Prediction Modes)：Magika 提供了不同的置信度级别，用于控制输出的“保守”程度。
- high-confidence：仅返回高置信度的结果。
- medium-confidence：默认选项，平衡准确率和覆盖率。
- best-guess：总是返回一个最佳猜测，即使置信度较低。
输出格式：支持丰富的输出格式，包括 JSON、JSONL 以及可通过 --format 参数自定义的模板（如 %p 路径、%l 标签、%s 得分等）。
性能：模型加载后，推理时间与文件大小无关，仅需约 5ms/文件，非常适合批量处理大量文件。

❓ 常见问题 (FAQ)

Q: 安装 Python 包后，magika 命令找不到？
- A: 确保 Python 的 bin 目录（如 ~/.local/bin）已添加到系统 PATH 环境变量中。使用 pipx install magika 通常会处理好路径问题。
Q: 如何获取最新版本？
- A: 根据安装方式不同：
  - Python: pip install --upgrade magika
  - Homebrew: brew upgrade magika
  - Cargo: cargo install --locked magika-cli
  - 安装脚本：重新运行安装脚本即可覆盖更新。
Q: Magika 与常规 file 命令有何不同？
- A: 传统的 file 命令基于硬编码的魔术字节规则，对规则外的文件容易误判。Magika 使用深度学习模型，能更好地识别文本类文件（如代码、配置、日志）和缺乏明显文件头（header）的格式，准确率更高，尤其擅长区分不同格式的纯文本文件。
Q: 我可以离线使用 Magika 吗？
- A: 可以。首次运行 CLI 或初始化 Python Magika 实例时，模型权重文件会被下载并缓存到本地（通常为 ~/.cache/magika/）。之后即可完全离线使用。