google / magika

#13

15,448849+956 todayPython

View on GitHub

Fast and accurate AI powered file content types detection

💡 Use Cases

最适合需要高精度、高性能文件内容类型识别的安全扫描、文件处理和自动化分类场景。

邮件附件安全扫描

Problem: 邮件系统需要准确识别上传附件的真实类型，防止恶意文件伪装成安全格式绕过安全检查。

Solution: 使用Magika的AI模型快速检测附件真实内容类型，准确率高达99%，确保文件被路由到正确的安全扫描器。

Example: Gmail使用Magika处理用户上传的附件，识别出看似是.jpg但实际是恶意脚本的文件，将其送入脚本扫描器而非图片处理器。

云盘文件分类

Problem: 云存储服务需要自动识别用户上传文件的类型以便正确预览、处理和存储，传统方法对文本和二进制文件识别不准。

Solution: 集成Magika的Python API，在文件上传时毫秒级识别200+种文件类型，特别是对文本格式（如代码、配置文件）有高精度识别。

Example: Google Drive使用Magika识别用户上传的.log、.conf、.py等文本文件，即使没有扩展名也能准确分类，支持正确的预览和搜索。

批量文件格式检测

Problem: 安全分析平台需要快速扫描大量可疑文件（如病毒样本库），传统工具速度慢或准确率不足。

Solution: 使用Magika命令行工具，单次调用可处理数千个文件，每个文件仅需约5ms，且支持递归目录扫描。

Example: VirusTotal集成Magika，每周处理数百亿个文件样本，快速识别未知二进制或混淆文本文件的真实类型，辅助威胁分析。

Web应用文件上传验证

Problem: Web应用需要在前端或后端验证用户上传文件的真实类型，防止恶意文件上传攻击。

Solution: 使用Magika的JavaScript/TypeScript绑定或Python API，在浏览器或服务器端快速验证文件内容，而非仅依赖文件扩展名。

Example: 在线表单应用在用户选择文件后，使用Magika的Web演示版技术实时检测文件真实类型，阻止伪装成PDF的EXE文件上传。

📊 Project Info

Language: Python
Stars: ⭐ 15,448
Forks: 849
Today: +956
Ranking: #13
Collection: Overall
Trending Date: April 17, 2026
Last Push: 4/16/2026

🏷️ Topics

深度学习ONNX文件类型检测安全扫描高性能轻量级安全工程师开发者

📸 Screenshots

5分钟快速上手Magika

Magika是一个AI驱动的快速文件类型检测工具，使用Python API轻松识别文件内容类型。

🖥️ OS

macOSWindowsLinux

⚙️ Runtime

Python3.8或更高

🔧 Tools

pip— Python包管理器，用于安装Magika

📝 Steps

安装Magika

使用pip安装Magika Python包。

安装Magika包

$ pip install magika

✓Expected: 安装成功，显示类似'Successfully installed magika'的消息。

💡如果遇到权限问题，可以尝试使用'pip install --user magika'。

运行简单检测

创建一个Python脚本，使用Magika检测一个示例文件。

使用Python单行命令检测README.md文件

$ python -c "from magika import Magika; m = Magika(); result = m.identify_path('README.md'); print(result)"

✓Expected: 输出类似{'path': 'README.md', 'label': 'Markdown', 'score': 0.99, 'mime_type': 'text/markdown'}的JSON结果。

💡确保当前目录有README.md文件，或替换为其他文件路径。

✅ 验证成功

如果看到文件类型检测结果，表示Magika已正确安装并运行。

✓输出包含'label'和'score'字段
✓检测结果准确（如README.md识别为Markdown）

⚡ Quick Tips

CLI使用'magika --help'查看命令行工具选项

文档访问Magika网站获取详细文档和示例

🔍 Troubleshooting

❓ pip安装失败，提示权限错误

→ 使用'pip install --user magika'或虚拟环境安装。

❓ Python命令找不到或版本过低

→ 检查Python安装，确保版本为3.8或更高，使用'python --version'验证。

❓ 检测输出为空或错误

→ 确认文件路径正确，文件存在且可读。

🎯 Next Steps

尝试检测多个文件

使用Python循环或CLI批量处理文件。

探索不同预测模式

在Magika API中设置'high-confidence'等模式调整检测精度。

Difficulty

初级

Est. Time

2-3小时

Target Audience

对AI应用感兴趣的Python初学者、安全分析新手、需要文件类型检测功能的开发者

🎯 What You'll Learn

学会安装和使用Magika进行文件类型检测，并了解如何将其集成到自己的Python项目中

📋 Prerequisites

Python基础了解

需要能运行Python脚本，理解基本的函数调用和变量赋值

命令行基础了解

需要在终端中执行简单的命令，如cd、ls等

pip包管理了解

需要知道如何使用pip安装Python包

📚 Resources

必看

Magika官方网站

包含核心概念、工作原理、模型详情、预测模式详解等完整文档

必看

GitHub README

项目首页，包含安装指南、快速示例和基本使用说明

🗺️ Learning Phases

环境准备与安装

⏱ 15-30分钟

安装Python环境

确保你的电脑上安装了Python 3.8或更高版本。可以在终端输入 `python --version` 或 `python3 --version` 来检查。如果没有安装，请从python.org官网下载安装。

💡推荐使用Python 3.10或更高版本以获得更好的兼容性

安装Magika Python包

打开终端（Windows用户可使用CMD或PowerShell），运行命令：`pip install magika`。这是最简单快捷的安装方式，它会同时安装命令行工具和Python库。

💡如果遇到权限问题，可以尝试 `pip install --user magika`。国内用户如果下载慢，可以使用清华镜像源：`pip install magika -i https://pypi.tuna.tsinghua.edu.cn/simple`

验证安装

安装完成后，在终端输入 `magika --version` 检查是否安装成功。同时可以输入 `python -c "import magika; print(magika.__version__)"` 验证Python模块是否可用。

💡如果 `magika` 命令找不到，可能需要重启终端或将Python的Scripts目录（Windows）或bin目录（Mac/Linux）添加到系统PATH中

快速上手：命令行初体验

⏱ 20-40分钟

检测单个文件

创建一个简单的文本文件（如test.txt），写入一些内容。然后在终端中运行：`magika test.txt`。观察输出结果，了解Magika返回的文件类型、置信度等信息。

💡可以尝试用不同的文件测试，如.py文件、.jpg图片、.pdf文档等，观察Magika的识别能力

批量检测文件

创建一个包含多个不同类型文件的文件夹，运行：`magika 文件夹路径/*` 或 `magika -r 文件夹路径`（递归扫描子目录）。

💡使用 `-r` 参数可以扫描整个目录树，非常适合批量处理

尝试不同置信度模式

Magika提供三种预测模式：`--prediction-mode high-confidence`（高置信度，最准确但可能返回未知）、`medium-confidence`（中等，平衡准确率和覆盖率）、`best-guess`（总是给出最佳猜测）。分别用这三种模式测试同一个文件，观察输出差异。

💡日常使用推荐 `medium-confidence`，在安全关键场景使用 `high-confidence`

查看详细输出

使用 `--json` 参数获取JSON格式的详细输出：`magika --json test.txt`。这包含了更多技术细节，适合程序化处理。

💡JSON输出包含了模型得分、是否可信、MIME类型等丰富信息

Python API集成

⏱ 30-60分钟

编写第一个Python脚本

创建一个Python文件（如demo.py），导入Magika模块：`from magika import Magika`。然后初始化检测器：`m = Magika()`。

💡首次初始化会下载并加载AI模型（约几MB），可能需要几秒钟时间

使用Python检测文件

在脚本中添加代码：`result = m.identify_path('test.txt')`，然后打印结果：`print(result.output)`。运行脚本查看效果。

💡`identify_path` 方法接受文件路径，`identify_bytes` 方法接受字节数据，`identify_content` 方法接受字符串内容

处理多个文件

编写一个循环，遍历目录中的所有文件，对每个文件调用 `identify_path`，并统计不同类型的文件数量。

💡Magika的Python API是线程安全的，可以在多线程环境中使用

自定义配置

尝试在初始化时传入参数：`m = Magika(prediction_mode="high_confidence")`。也可以设置 `dont_use_gpu=True` 强制使用CPU（默认会自动使用GPU如果可用）。

💡在服务器环境或容器中，如果不想使用GPU，可以明确指定只使用CPU

实战应用

⏱ 30-45分钟

构建简单的文件分类器

编写一个脚本，扫描指定目录，根据Magika检测的结果将文件分类到不同的子文件夹中（如文本文件、图片、文档、代码等）。

💡可以使用 `result.output.ct_label` 获取人类可读的类型标签，或 `result.output.mime_type` 获取MIME类型

集成到现有项目

假设你有一个处理用户上传文件的应用，在保存文件前使用Magika验证文件类型是否允许（如只允许图片和PDF）。编写一个验证函数，如果类型不允许则拒绝保存。

💡对于安全敏感的应用，务必使用 `high_confidence` 模式，并对未知类型保持警惕

性能测试

创建一个包含1000个文件的测试集，使用Python的time模块测量Magika批量处理这些文件所需的时间，计算平均每个文件的处理时间。

💡Magika的设计目标是在毫秒级完成检测，你的测试结果应该与此相符。首次运行会慢一些，因为需要加载模型

⚠️ Common Mistakes

❌ 安装后magika命令找不到

✅ 这通常是因为Python的Scripts/bin目录不在PATH中。可以：1) 使用完整路径调用（如 `python -m magika.cli`）；2) 将Python安装目录下的Scripts（Windows）或bin（Mac/Linux）添加到系统PATH；3) 重启终端

❌ 首次运行特别慢

✅ 第一次初始化Magika时需要下载和加载AI模型（约几MB），这是正常现象。后续调用会非常快。模型默认会缓存到本地，下次启动就不需要重新下载了

❌ 对某些文件类型识别不准确

✅ 1) 确保文件有实际内容（空文件难以识别）；2) 尝试不同的预测模式；3) 检查文件是否损坏；4) 某些非常见或自定义格式可能不在Magika的训练集中，这时会返回通用类型（如Generic text document）

❌ 在Python中重复初始化Magika

✅ Magika对象初始化成本较高（需要加载模型）。应该全局初始化一次，然后重复使用同一个实例，而不是每次检测都创建新实例

❌ 忽略置信度信息

✅ Magika的输出中包含置信度分数和是否可信的标志。在关键应用中，不仅要看检测出的类型，还要关注置信度，对于低置信度的结果应该采取保守策略（如拒绝或进一步验证）

🚀 Next Steps

学完基础后可以继续探索的方向：1) 深入研究Magika的AI模型架构和训练过程；2) 学习如何使用其他语言绑定（如JavaScript/TypeScript、Go、Rust）；3) 将Magika集成到Web应用或自动化工作流中；4) 研究如何扩展Magika支持自定义文件类型；5) 了解Magika在Google内部和VirusTotal等平台的实际应用案例