Magika 的 JavaScript/TypeScript 库全解magika JS 包的安装、API 用法与内部实现【免费下载链接】magikaFast and accurate AI powered file content types detection项目地址: https://gitcode.com/GitHub_Trending/ma/magikaMagika 是一个基于深度学习的内容类型content type检测工具而其js/目录下的MagikaJSnpm 包名magika让开发者可以直接在浏览器或 Node.js 中完成文件类型识别无需依赖 Python 环境或本地 CLI。本文以 js/README.md 为骨架完整覆盖其安装方式、Node 与浏览器两端的最小用法、magika-js命令行工具、模型与配置的加载策略和开发测试流程并结合 js/magika.ts、js/magika_node.ts 等源码逐层剖析预测管线、阈值判定与流式识别的实现原理。一、MagikaJS 的定位与双端架构MagikaJS 的核心目标是“在浏览器或 Node 中使用 Magika”README 原文Use Magika in the browser or in Node!。它通过 TensorFlow.js 在纯 JS 环境中运行 Magika 模型因此无需编译环境或 ONNX Runtime这也是它与仓库中 rust/、go/ 等其他语言绑定在运行方式上的本质区别。从 js/package.json 可以确认该包的几个关键事实当前仓库版本为0.2.14Apache-2.0 协议核心依赖tensorflow/tfjs^4.19.0可选依赖tensorflow/tfjs-node、chalk、commander——其中tfjs-node是 Node 端本地加载模型所需的推理后端chalk与commander则仅服务于命令行工具 js/index.ts双端导出exports字段按运行环境做了条件分发——Node 环境下import/require默认解析到magika_node即MagikaNode类浏览器等其他环境解析到magika即Magika类因此同一句import { Magika } from magika在两种环境中拿到的是不同实现CLI 入口bin字段将magika-js命令指向./dist/cjs/index.js。源码结构上整个库分为两个入口类与四个支撑模块文件职责js/magika.tsMagika基类浏览器/通用端负责加载模型与配置、字节数组识别js/magika_node.tsMagikaNode继承自MagikaNode 端新增本地文件加载与流式识别js/src/model.tsModel基类封装tf.loadGraphModel推理与阈值判定js/src/model_node.tsModelNode继承Model通过tfjs-node的文件系统 handler 从本地磁盘加载模型js/src/config.tsConfig从 URL 或本地 JSON 文件加载标签表与输入参数js/src/moduleFeatures.tsModelFeatures将头/中/尾三段字节编码为模型输入特征js/src/magikaOptions.tsMagikaOptions接口modelURL/modelPath/configURL/configPath四个可选字段完整的 API 文档由 TypeScript 源码自动派生js/package.json 中的make-docs脚本documentation build *.ts ... -o ../docs/js.md将 js/magika.ts 与 js/magika_node.ts 的 JSDoc 注释生成到 docs/js.md因此该方法级 API 与源码永远保持同步。二、安装与最小可用示例安装按 js/README.md 说明安装命令为npm install magikaNode 环境README 给出的最小 Node 用法如下MagikaNode即为 package.json 在 Node 环境下的默认导出import { readFile } from fs/promises; import { MagikaNode as Magika } from magika; const data await readFile(some file); const magika new Magika(); await magika.load(); const prediction await magika.identifyBytes(data); console.log(prediction);prediction是一个ModelResult仅包含{ label, score }两个字段见 js/src/model.ts 中的接口定义label为识别出的内容类型ContentTypescore为模型给出的置信度0~1 区间js/test/magika.test.ts 中有针对分数区间的性质测试验证。浏览器环境浏览器侧使用基类Magika从File对象中取出字节后同样调用identifyBytesREADME 原文示例import { Magika } from magika; const file new File([# Hello I am a markdown file], hello.md); const fileBytes new Uint8Array(await file.arrayBuffer()); const magika new Magika(); await magika.load(); const prediction await magika.identifyBytes(fileBytes); console.log(prediction);仓库中还提供了一个可交互的前端演示组件 website/src/components/FileClassifierDemo.vue可参考其如何在 Vue 组件中组织这套调用流程。完整概率输出identifyBytesFull两个入口类都提供了identifyBytesFull方法js/magika.ts、js/magika_node.ts返回类型为ModelResultLabels在{ label, score }之外额外附带一个labels字段——一张“内容类型名 → 得分”的完整映射表实现见 js/magika.ts 的_getLabelsResult。当你需要对比多个候选类型的置信度例如区分html与markdown的相对把握时应使用它而不是identifyBytes。三、模型与配置的加载策略MagikaJS 在设计上对“模型从哪里来”保持灵活这是 js/README.md 专门用一节强调的要点Node 与浏览器版本都接受 URL 以异步加载模型model.json与配置config.json这两个资产await magika.load({ modelURL: https://..., configURL: https://..., });Node 版本MagikaNode额外支持从本地磁盘加载README 原文示例await magika.load({ modelPath: ./assets/..., configPath: ./assets/... });对照源码可以确认其精确行为默认值Magika类声明了两个静态常量js/magika.ts——CONFIG_URL https://google.github.io/magika/model/config.json、MODEL_URL https://google.github.io/magika/model/model.json。load()不传参数时即从这两个官方地址加载js/magika.ts。优先级规则MagikaNode.load()的逻辑是js/magika_node.ts——若options.configPath非空则走config.loadFile(path)否则回退到configURL未提供时用默认 URL模型侧同理modelPath优先于modelURL。也就是说 path 与 URL 可以混合例如只用modelPath指定本地模型、配置仍走网络。底层加载器URL 加载走 js/src/model.ts 的tf.loadGraphModel(modelURL)本地加载走 js/src/model_node.ts 的tfn.io.fileSystem(modelPath)这就是tensorflow/tfjs-node被列为 optionalDependencies 的原因。幂等性Config.loadUrl/loadFile在loaded为 true 时直接返回Model.loadUrl在模型已加载时也不再加载重复调用load()不会产生副作用。此外源码中还暴露了Magika.create(options)这个静态工厂js/magika.ts等价于newload()的组合适合一次性构造的场景。配置文件里有什么以仓库随附的 website/public/model/config.json 为例配置 JSON 包含input_size_beg/input_size_mid/input_size_end文件头、中、尾三段特征的字节数当前模型均为 512min_file_size_for_dl进入深度模型推理的最小文件长度当前为 16padding_token特征填充用的哨兵值256labels每个标签的{ name, threshold, is_text }三元组数组例如asm阈值为 0.85 且is_text: truec阈值为 0.7多数二进制类型阈值为 0.95。Config类的解析逻辑在 js/src/config.ts。需要注意一个源码层面的观察从当前setConfig实现看begBytes、midBytes、endBytes三个字段目前统一读取config.input_size_beg由于仓库现有模型配置中三个input_size_*恰好都等于 512实际行为与完整读取三者等价但若使用第三方配置且三段长度不一致应以源码实际读取的input_size_beg为准。四、预测管线的内部实现从字节到标签identifyBytes背后的完整管线在 js/magika.ts 中理解它有助于正确使用该库短文件快速路径。当输入长度小于等于minFileSizeForDl时不跑模型直接由_getResultForAFewBytesjs/magika.ts判定空文件返回emptyscore 恒为 1.0能用 UTF-8 严格解码TextDecoder(utf-8, {fatal: true})的视为纯文本返回generic_text否则返回unknown。三段特征切片。对更长的文件先整体转为Uint16Array再切出三段头部fileArray.slice(0, config.begBytes)中部以文件正中点为中心、长度config.midBytes的窗口halfpoint处取窗不足时以填充补齐尾部文件最后config.endBytes个字节不足时前置填充endOffset记录填充量。这三段通过ModelFeatures的withStart/withMiddle/withEnd组装js/src/moduleFeatures.ts填充值来自padding_token。这种“头中尾”采样让 Magika 无需读取整个大文件即可保留关键位置信息。推理与阈值判定。Model.predictjs/src/model.ts把特征包装成tf.tensor([features])执行图模型推理用argMax取概率最大的索引generateResultFromPredictionjs/src/model.ts随后做关键判定若最高概率≥ 该标签的threshold输出该标签若未达标但该标签is_text为真降级输出generic_text否则输出unknown。这正是每个内容类型拥有独立阈值config.json中 0.5~0.95 不等的意义对易误判的文本类标签放宽门槛对特征明确的二进制类标签要求高置信度。Node 端的流式识别identifyStreamMagikaNode独有的identifyStream(stream, length)/identifyStreamFull(stream, length)js/magika_node.ts允许直接对ReadStream做识别而不需要把整个文件读入内存——其实现js/magika_node.ts在data事件回调中追踪stream.bytesRead首个数据块即填充withStart当流推进到文件中点附近halfpoint/halfpointCap窗口时截取中部特征流结束时stream.bytesRead length截取尾部特征。length参数是必需的它让库在只保留当前块lastChunk的常显存条件下计算出中点位置。处理完最后一个块后await finished(stream)再执行与identifyBytes相同的predict路径。对超大文件或管道式数据如网络传输落地前的拦截场景这是浏览器端identifyBytes的重要补充。五、magika-js 命令行工具js/README.md 对这一节的定位很明确常规用途建议直接使用官方 Python CLIpip install magika因为它支持批处理与递归查找文件magika-js的价值在于加载 TensorFlow.js 模型并快速验证其行为是否符合预期README 原文“This one is useful to load the TensorflowJS model and see that it works as expected”。安装与运行方式README 原文npm install -g magika magika-js some files--help输出摘自 READMEMagika JS - file type detection with ML. https://google.github.io/magika Arguments: paths Paths of the files to detect Options: --json-output Format output in JSON --model-url model-url Model URL (default: https://google.github.io/magika/model/model.json) --config-url config-url Config URL (default: https://google.github.io/magika/model/config.json) -h, --help display help for command对照源码 js/index.ts有两点补充命令行实际上还支持--model-path model-path与--config-path config-path两个本地路径选项与 README 的 help 文本相比是源码中额外实现的可将modelPath/configPath与 URL 选项一并发给magika.load()CLI 内部使用Promise.all并行处理多个路径读文件失败时打印Skipping file并跳过--json-output模式下输出{ path, ...prediction }的 JSON 对象。该命令由 js/package.json 的bin字段注册为magika-js指向构建产物dist/cjs/index.js。六、构建、本地联调与测试开发构建README “Development” 一节原文流程使用 GitHub 托管的模型yarn install yarn run build yarn run bin -- README.md使用本地模型依赖 website 子项目的 dev server 托管 website/public/model/yarn install yarn run build (cd ../website; yarn install; yarn run dev) yarn run bin --model-url http://localhost:5173/magika/model/model.json --config-url http://localhost:5173/magika/model/config.json ../tests_data/mitra/*对照 js/package.json 的scripts可理解每条命令的实际含义build清空dist/后用 TypeScript 分别编译 ESM 与 CJS 两套产物tsconfig.esm.json/tsconfig.cjs.json再执行postBuild.js后处理binTF_CPP_MIN_LOG_LEVEL1 node ./dist/mjs/index.js——压低 TensorFlow C 后端的日志级别后运行 CLImake-docs由源码 JSDoc 重新生成 docs/js.md。测试README 给出的测试流程yarn install yarn run build yarn run testtest脚本实际执行 Jestjs/package.json 中TF_CPP_MIN_LOG_LEVEL1 node node_modules/jest/bin/jest.js。测试文件 js/test/magika.test.ts 揭示了相当完整的验证面加载方式双轨验证should load default model from url确认无参load()从默认 URL 加载且未触碰 tfjs-nodeshould load model from file path将config.json、model.json及其weightsManifest中声明的权重分片下载到临时目录再以configPath/modelPath加载验证本地路径分支配合 js/test/tfnHook.ts 对tfn的 mock分数性质测试基于fast-check的随机性质测试断言任意 0~10 字节的随机输入其score都落在[0, 1]回归数据集beforeAll阶段收集 tests_data/basic 与 tests_data/mitra 两个目录下的全部测试文件以所在目录名作为期望标签覆盖c、javascript、zip、mp3、pdf、elf、pebin等大量类型并显式跳过 V2 模型尚未覆盖的dockerfile、toml、typescript、yara等标签。七、注意事项与引用误报反馈README 建议对误报false positives在 GitHub 上开 issue仓库的 tests_data/current_missdetections 目录保留了已知的漏检/误检样本如html/malformed-html-gh-521.html可作为了解当前识别边界的参考。环境前提Node 端使用本地模型路径modelPath需要tensorflow/tfjs-node这一可选依赖被成功安装浏览器端则天然只走 URL 分支。模型默认从 Google 官方托管地址下载离线环境应自行托管model.json、权重分片与config.json可参考仓库 website/public/model/ 的文件组织。引用若将该软件用于研究项目提供了 BibTeX 引用条目见 js/README.md 的 Citation 一节与仓库根的 CITATION.cff。八、小结MagikaJS 用一条import { Magika } from magika把 Magika 的深度模型识别能力带入了 JS 生态浏览器端Magika与 Node 端MagikaNode共享同一套“头/中/尾三段特征 每标签阈值判定”的预测管线js/magika.tsNode 端额外提供本地文件加载js/src/model_node.ts与低显存的流式识别js/magika_node.ts模型与配置支持 URL/本地路径两种来源并可混合指定magika-jsCLIjs/index.ts则承担了模型加载冒烟验证的角色。测试体系Jest fast-check tests_data/ 回归数据集保证了 URL 加载、本地加载、分数区间与多类型识别行为的持续可验证性。对需要在 JS 服务、浏览器应用或 Node 脚本中做内容类型检测的开发者这套 API 已可直接复制使用更大规模的文件批处理与递归扫描场景官方建议转用 Python CLI见主 README.md。【免费下载链接】magikaFast and accurate AI powered file content types detection项目地址: https://gitcode.com/GitHub_Trending/ma/magika创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
