magika 是什么?

Magika 是 Google 出的 AI 文件类型检测工具:用一个高度优化的小型深度学习模型(仅几 MB)在毫秒级、单 CPU 上也能精确识别文件内容类型。它在约 1 亿样本、200+ 内容类型(二进制 + 文本)上训练评测,测试集平均约 99% 准确率,尤其在文本类型上明显优于传统方法(如 libmagic/file 命令)。它已在 Google 内部大规模用于把 Gmail、Drive、Safe Browsing 的文件路由到正确的安全与内容策略扫描器,每周处理上千亿样本,并集成进 VirusTotal、abuse.ch。CLI 用 Rust,另有 Python API 与 Rust/JS/Go 绑定。Apache-2.0,研究论文发表于 ICSE 2025。

⭐ 16,663 Stars 🍴 998 Forks Python Apache-2.0 作者: google
来源:README 顶部/Highlights;GitHub desc,license Apache-2.0 查看 GitHub 仓库 →

为什么值得关注

约 1.7 万星、自 2023 年就存在并持续维护。热度来自它精准解决了一个老问题:传统 file/libmagic 靠魔数和规则、对文本和混淆文件常出错,而 Magika 用小而快的深度模型把『判断这是什么文件』做到 99% 准确、毫秒级、单 CPU 可跑,还有 Google 的大规模生产验证和 ICSE 论文背书,安全/取证/数据管线领域都用得上。

来源:GitHub 17,035 stars / 1,044 forks,created 2023-08-22;README 顶部

核心功能

小模型、毫秒级、单 CPU

自定义深度模型仅几 MB,模型加载后每文件推理约 5ms,单 CPU 即可;推理时间近乎与文件大小无关——只用文件内容的有限子集,可同时处理上千文件、支持 -r 递归扫目录。

来源:README Highlights(小模型/5ms/near-constant)
200+ 内容类型、约 99% 准确

在约 1 亿文件、200+ 内容类型(二进制与文本)上训练评测,测试集平均约 99% precision/recall,尤其在文本内容类型上超越现有方法。

来源:README 顶部/Highlights
阈值与置信度模式

采用每内容类型的阈值系统决定是否『信任』模型预测,否则返回 Generic text document / Unknown binary data 等通用标签;可用 high-confidence / medium-confidence / best-guess 不同预测模式控制对错误的容忍度。

来源:README Highlights(threshold/prediction modes)
多语言客户端与绑定

CLI 用 Rust 写,提供 Python API,以及 Rust、JavaScript/TypeScript(实验性 npm,驱动浏览器内本地运行的 web demo)和 GoLang(WIP)绑定,可嵌入各类工具链。

来源:README Highlights/Installation;tree(rust/python/js/go)
生产级安全集成

在 Google 内部把 Gmail/Drive/Safe Browsing 文件路由到正确的安全与内容策略扫描器(每周上千亿样本),并已集成进 VirusTotal 与 abuse.ch,是经过大规模实战验证的安全基础组件。

来源:README 顶部(used at scale/VirusTotal/abuse.ch)

技术架构

多语言 monorepo,围绕一个共享的小型深度学习模型构建:assets/models 下是训练好的标准模型(standard_v3_3 等,含 200+ 内容类型定义)。各语言实现把同一模型跑起来——rust/(CLI 主体,性能最佳)、python/(Python API + 包)、js/(TypeScript 实现 magika.ts/magika-node.ts/magika-cli.ts,experimental npm,并驱动浏览器内本地推理的 web demo)、go/(用 onnx 跑模型,WIP)。模型推理只取文件内容的有限子集做特征、近常数时间,配合每类型阈值与置信度模式输出标签或通用回退。tests_data/ 是测试样本,website/website-ng/ 是站点与 demo。整体是『一个共享小模型 + 多语言客户端/绑定 + 阈值/置信度后处理』的设计,强调小、快、可嵌入、可在客户端/浏览器本地运行(隐私友好)。

来源:README Highlights/Installation;tree(rust/python/js/go、assets/models、tests_data)

项目知识图谱

知识图谱:项目核心节点(中心)+ 核心功能(内环六边形)+ 关键技术依赖(外环 chip) 自研小型 DL 模型(几 MB)自研小型 DL 模… ONNX Runtime(go/rust 推理)ONNX Runtime(… PyPI magika / npm magikaPyPI magika /… 200+ 内容类型模型(standard_v3_x)200+ 内容类型模… 小模型、毫秒级、单 CPU 200+ 内容类型、约 99% 准确200+ 内容类型、约 99… 阈值与置信度模式 多语言客户端与绑定 生产级安全集成 magika 项目本体 核心功能 关键依赖

中心为项目本体,内环 = 核心功能模块,外环 = 关键技术依赖;按 deep.json 中的 core_features 与 tech_stack.key_deps 自动生成

技术栈

语言Rust(CLI)+ Python + JS/TS + Go(绑定)框架自定义深度学习模型(ONNX 推理)
自研小型 DL 模型(几 MB)ONNX Runtime(go/rust 推理)PyPI magika / npm magika200+ 内容类型模型(standard_v3_x)
本地/客户端运行,单 CPU 即可,毫秒级;可浏览器内本地推理;无需联网
来源:README Installation/Highlights;tree(go/onnx、js)

快速上手

CLI(Rust):按 README 安装后 `magika <文件>`,加 -r 递归扫目录、可一次传上千文件。Python:`pip install magika`,用 Magika 类对文件/字节做识别拿到内容类型与置信度。JS/TS:实验性 npm 包 magika,可在 Node 或浏览器本地推理(web demo 即如此)。Go 绑定 WIP。可用 high-confidence/medium-confidence/best-guess 模式调节容错。也可不装任何东西、直接用官网浏览器内的 web demo 体验(本地运行)。
来源:README Getting Started/Installation/Quick Start

使用场景

适合:①安全/取证/反滥用场景,需要可靠判断上传文件真实类型(不被扩展名/伪装欺骗)再路由到对应扫描器;②数据管线、内容平台、防病毒/沙箱前置的文件分类;③需要在客户端/浏览器本地、低延迟、单 CPU 跑文件类型识别且注重隐私的场景;④想把准确的 file-type 检测嵌进 Rust/Python/JS/Go 工具链的人。不适合:只需粗略按扩展名判断的轻量场景(无需上模型);以及对极少见/自定义私有格式的识别(不在 200+ 类型内可能回退为通用标签)。

来源:README 顶部/Highlights,结合定位推断

优势与局限

优势

  • 准确率高且实测:200+ 类型约 99%,尤其文本类远超传统 libmagic/file,并有 ICSE 论文与大规模生产验证
  • 小、快、可嵌入:模型几 MB、单 CPU 毫秒级、近常数时间,可在客户端甚至浏览器本地跑,隐私友好
  • 多语言覆盖:Rust CLI + Python/JS/Go 绑定,易接入各类工具链与安全管线
  • 工程成熟:Google 出品、Apache-2.0、OpenSSF 最佳实践、CodeQL,已集成 VirusTotal/abuse.ch
  • 可控性好:每类型阈值 + 三档置信度模式,可按需在准确与覆盖间权衡

局限

  • 识别范围限于训练覆盖的 200+ 内容类型,少见/私有/自定义格式可能只得到通用回退标签
  • 是基于内容的概率判断,对抗性构造或边界样本仍可能误判,不能当绝对真相
  • 只解决『是什么类型』,不做内容安全/恶意性判断——需配合后续扫描器
  • 部分绑定(Go)仍 WIP、JS npm 标实验性,非 Rust/Python 路径成熟度有差异
  • 模型加载有一次性开销,超大批量/服务化需自行做好常驻与并发
来源:README Highlights/Disclaimer;模型方法的固有局限

最新版本

按语言分别发布:CLI v1.1.0(2026-04-24,Rust)、python-v1.0.2(2026-02-27)等,模型为 standard_v3_3;仓库自 2023-08 持续维护(最近 push 2026-05-20),是成熟且仍活跃迭代的项目。

来源:GitHub Releases cli/v1.1.0、python-v1.0.2;pushed_at 2026-05-20

总结评价

Magika 是『用小 AI 模型把一件老工具做对』的范例:传统 file/libmagic 在文本和伪装文件上常翻车,而它用几 MB 的模型在单 CPU 毫秒级做到 200+ 类型约 99% 准确,还能在浏览器本地跑、隐私友好,背后有 Google 的千亿级生产验证和 ICSE 论文,1.7 万星实至名归。它的边界也清楚:只判断『是什么类型』、不判恶意性,识别范围限于训练覆盖的类型、罕见格式会回退通用标签,且仍是概率判断。对做安全、取证、内容平台或数据管线、需要可靠 file-type 检测的人,它基本是当前最好的开源选择,直接嵌进 Rust/Python/JS/Go 工具链即可。

来源:综合 README 定位/能力、tree 多语言结构、局限与发布状态的事实判断
透明度声明
本页内容由 AI(大语言模型)基于以下公开材料自动生成:GitHub README、代码目录结构、依赖文件、Release 信息。 分析时间: 2026-05-22 23:27. 质量评分: 100/100.

数据来源:README、GitHub API、依赖文件