AI 驱动的文件真实内容检测工具：Magika 开源

相信有朋友做过企业AI知识项目检索增强生成 RAG 的项目，如果文件来源是未知的，出于安全的需要，需要检测恶意软件伪装成 PDF、脚本伪装成图片，那么这个检测工具你一定用得上。

Magika 是 Google 开源的一款 AI 驱动的文件类型检测工具，利用深度学习精确识别文件的真实内容类型（不依赖扩展名）。

核心能力：

核心能力

使用方式

• • CLI（Rust 编写）：magika file.py --json
• • Python：pip install magika
• • JavaScript/TypeScript：npm install magika（支持浏览器端运行）
• • Rust / Go 绑定也在开发中

是否会使用大模型接口？

不会。

Magika 完全不使用任何大模型 API（OpenAI、Gemini、Claude 等），也不进行任何网络调用。

它的技术架构是这样的：

1. 自训练专用小模型：Google 自己训练了一个定制的深度学习模型，专门用于文件类型检测，大小仅几 MB
2. ONNX Runtime 本地推理：模型格式为 .onnx，通过 ONNX Runtime 的 CPUExecutionProvider 在本地 CPU 上运行
3. 完全离线：模型文件随 Python/JS 包一起分发，推理时不发起任何 HTTP 请求
4. 浏览器也能跑：官方提供了 Web Demo，模型在浏览器本地运行，无需服务端

简单说：它是一个本地小模型，不是调大模型 API。

那么，如何使用呢？

调用实例是怎样的，会尝试加载文件然后使用模型识别开头部分吗？

还是会扫描整个文件，如果文件比较大会怎样（例如视频文件等）？

Python API

from magika import Magika

m = Magika()

# 方式1: 直接识别字节内容
res = m.identify_bytes(b'function log(msg) {console.log(msg);}')
print(res.output.label)   # javascript
print(res.output.mime_type)  # text/javascript
print(res.score)           # 0.997

# 方式2: 识别文件路径（推荐用于大文件）
res = m.identify_path('./video.mp4')
print(res.output.label)   # mp4

# 方式3: 从已打开的流中识别（同样推荐用于大文件）
with open('./large_file.bin', 'rb') as f:
    res = m.identify_stream(f)

CLI

# 普通识别
magika file.py

# JSON 输出（含置信度）
magika file.py --json

# 递归扫描整个目录
magika -r ./project/

# 从标准输入读取
cat data.bin | magika -

JavaScript

npm install magika

import { Magika } from 'magika';
const m = await Magika.create();
const result = await m.identifyBytes(new Uint8Array([...]));
console.log(result.output.label);

内部机制：只读文件开头，不扫描全文件

Magika 只读取文件的前面几个 chunk，通常最多约 2KB 的数据。

它从不需要加载整个文件到内存。

表格

在 identify_path() 和 identify_stream() 中，Magika 会用 seek() 跳到文件开头读取一小段，然后直接返回，不会把整个 2GB 视频加载到内存。

为什么只读开头就够了？

绝大多数文件格式在文件头部都有特征性的 magic bytes 或特定的结构模式。比如：

• • MP4 文件开头会有 ftyp box
• • PNG 开头是 \x89PNG\r\n\x1a\n
• • PDF 开头是 %PDF-
• • ELF 开头是 \x7fELF
• • Python 源码开头常见 #!/usr/bin 或 import / #

深度学习模型从这些头部字节中提取特征，就能以极高置信度判断文件类型，不需要扫描整个文件。

预测模式与置信度

from magika import Magika, PredictionMode

# 高置信度模式（默认）：只有模型很有把握才返回具体类型，否则返回 generic 标签
m = Magika(prediction_mode=PredictionMode.HIGH_CONFIDENCE)

# 中等置信度模式
m = Magika(prediction_mode=PredictionMode.MEDIUM_CONFIDENCE)

# 最佳猜测模式：即使置信度低也给一个猜测
m = Magika(prediction_mode=PredictionMode.BEST_GUESS)

每个内容类型都有一个预设的置信度阈值。

模型预测后，如果分数不达标，Magika 会"覆盖"模型结果，返回通用标签如 txt（文本类）或 unknown（二进制类）。

Magika 只读文件开头 ~2KB，用本地 ONNX 模型推理（约 5ms），与文件大小无关。 即使是几 GB 的视频，也只 seek 读取头部的 magic bytes，不会把整个文件加载到内存。这是它能在 Google 内部每周处理数千亿文件的关键原因。

优势在哪里？

既然它只识别文件头部分，不使用训练好的 ONNX 模型，使用传统的分类识别也可以达到相同目的，这个项目的优势在哪里？

区别在于：传统工具靠人手写规则，Magika 靠数据学模式。

这两种方法在面对不同文件类型时，能力差距非常大。

传统方案能做什么、不能做什么

传统工具（Unix file 命令、libmagic）的核心思路是维护一个规则数据库，每条规则大致是"如果文件开头第 N 个字节是 0x89PNG，那就是 PNG"。

二进制格式几乎都有明确的 magic bytes，写规则就能匹配，传统工具够用：

表格

但在文本文件上，传统工具基本抓瞎。

比如，所有文件的开头都是纯文本，没有任何二进制 magic bytes：

文件1:  import os\nimport sys\n\ndef main():\n    ...
文件2:  const express = require('express');\nconst app...
文件3:  package com.example;\n\npublic class Main {\n...
文件4:  #include <stdio.h>\n\nint main() {\n    ...
文件5:  ---\ntitle: My Post\ndate: 2024-01-01\n---\n\n...
文件6:  {\n  "name": "my-project",\n  "version": "1.0...

全部以可打印字符开头。

传统 file 命令对上面这些文件的输出通常是：

$ file main.py
main.py: ASCII text         ← 只知道是文本，不知道是 Python

$ file index.js
index.js: ASCII text        ← 同理

$ file config.yaml
config.yaml: ASCII text     ← YAML 还是 Markdown？不知道

这就是 Magika 的真正优势所在。

Magika 的优势：靠数据学到"人看不到的模式"

Magika 的深度学习模型在 1 亿文件上训练，覆盖 200+ 类型。

它从文件头部的 2KB 字节中学到的是统计层面的模式，不需要硬规则编码。

模型能学到：

• Token 共现模式：import + def + : → 大概率 Python；const + => + { → 大概率 JavaScript
• 缩进和空格分布：Python 用 4 空格缩进的比例远高于其他语言；YAML 用 2 空格居多
• shebang 行：#!/usr/bin/env python3 vs #!/bin/bash
• 注释风格：// vs # vs /* */
• 微妙差异：JSON ({"") vs JSONL ({"a":1}\n{"a":2}) 的区别

具体优势总结

论文数据佐证

Magika 的 ICSE 2025 论文中对文本文件类型的识别，相比 file 命令 + libmagic 有数量级的提升。

尤其对于编程语言源码、配置文件、标记语言等文本格式，这恰恰是传统 magic-byte 方案的结构性弱点。

对二进制文件（PNG/PDF/ZIP），传统 magic bytes 匹配就够用。 但对文本文件（Python/JS/YAML/Markdown/JSON 等），传统方案只能告诉你"这是文本"，而 Magika 的深度学习模型能从文件头的字节分布中学习到语言级别的模式，精确区分 100+ 种文本格式。 它的优势不在替换传统方案的二进制检测，而在于做到了传统方案根本做不到的事：精确识别无 magic bytes 的文本文件类型。

官方地址：https://github.com/google/magika