在 Lobster 中使用 FlatBuffersMNN 仓库 3rd_party/flatbuffers 的读写与 JSON 互转实战指南【免费下载链接】MNNMNN: A blazing-fast, lightweight inference engine battle-tested by Alibaba, powering high-performance on-device LLMs and Edge AI.项目地址: https://gitcode.com/GitHub_Trending/mn/MNN本指南以 MNN 仓库内置的 FlatBuffers 子模块3rd_party/flatbuffers中的 Lobster 语言绑定文档为核心系统讲解如何在 Lobster 语言中通过flatc --lobster生成代码、零拷贝读取 FlatBuffer 二进制、构造与写出二进制缓冲以及完成 JSON 与 FlatBuffers 双向转换。读完本文你将掌握 Lobster 场景下 FlatBuffers 从 schema 到读写、再到文本互转的完整链路并能直接复用仓库内samples与tests中的可运行示例进行验证。前置准备先掌握 FlatBuffers 基础在深入 Lobster 绑定的细节之前需要先具备 FlatBuffers 的通用基础。关联文档明确指出通用教程Tutorial页包含了对所有受支持语言含 Lobster的完整使用指南本页只讨论 Lobster 特有的细节。因此动手之前应当熟悉以下内容构建flatcFlatBuffers 模式编译器schema compiler使用 schema 编译器掌握flatc的命令行选项与代码生成流程编写 schema理解.fbs文件中的table、struct、enum、union、vector等核心概念。本仓库内的 monster.fbs 是贯穿本文全部示例的 schema它定义了Vec3struct、Weapontable、Monstertable、Color与Equipmentenum/union等类型是观察 Lobster 生成代码与运行时行为的最佳标本。此外monsterdata.json 提供了对应的 JSON 形态数据monsterdata_test.mon 则是测试用的二进制线格式文件。Lobster 库代码与测试代码的位置库代码位置FlatBuffers 的 Lobster 运行时库代码位于 FlatBuffers 源码树的lobster/目录。需要注意当前仓库的实际情况MNN 的3rd_party/flatbuffers以第三方依赖形式内嵌其顶层目录CMake、docs、grpc、include、reflection、samples、src、tests等中并未包含lobster/运行时目录即flatbuffers.lobster运行时文件需要从 Lobster / FlatBuffers 官方源获取。仓库中保留的是与 Lobster 相关的示例、生成代码与测试它们通过include from ../lobster/与include flatbuffers.lobster见 sample_binary.lobster引用该运行时。测试代码与运行方式Lobster 绑定的测试代码位于 FlatBuffers 的tests/目录本仓库对应的文件是 lobstertest.lobster配套的生成代码为 monster_test_generated.lobster。运行测试的方式很简单lobster lobstertest.lobsterLobster 语言本身需从其官方主页或 GitHub 仓库获取并针对你的平台完成构建。运行环境上Lobster 既可作为字节码 VM 解释执行也可编译为 C 后执行这一点直接影响性能表现详见后文速度一节。从源码看lobstertest.lobster的测试覆盖了三个关键场景读取规范的二进制文件read_file(monsterdata_test.mon)读入由 C 实现产出的线格式数据再交给生成的MyGame_Example_GetRootAsMonster解析并逐字段断言lobstertest.lobster用生成代码构造二进制通过flatbuffers_builder配合生成的MonsterStart / MonsterAdd* / MonsterEnd系列函数自建 Monster 对象再调用check_read_buffer校验并把结果写回monsterdata_lobster_wire.monlobstertest.lobsterJSON 往返测试二进制转 JSON、JSON 再转二进制最终仍通过check_read_buffer验证内容一致lobstertest.lobster。由此可见Lobster 绑定在读写两个方向上都与 C 侧产出的线格式完全互通。生成 Lobster 代码flatc 的 --lobster 选项在 Lobster 中读写 FlatBuffer 的第一步是用flatc从 schema 生成 Lobster 类flatc --lobster monster.fbs--lobster选项在编译器主入口 flatc_main.cpp 中注册对应实现位于 idl_gen_lobster.cpp。生成的.lobster文件如 monster_generated.lobster以// automatically generated by the FlatBuffers compiler, do not modify开头结构上包含四类产物命名空间与枚举namespace MyGame_Sample把生成的符号归入统一前缀enum 声明Color_Red、Equipment_Weapon等常量struct 占位声明struct Vec3/struct Monster/struct Weapon先声明、后定义读取访问器struct Vec3 : flatbuffers_handle中定义x()、y()、z()通过buf_.read_float32_le(pos_ 0)直接按偏移读取内存struct Monster : flatbuffers_handle中定义pos()、hp()、name()、inventory(i)、weapons(i)、equipped_as_Weapon()等字段访问器monster_generated.lobster写入辅助函数每个 table 对应XxxStart()、XxxAddField(...)、XxxEnd()每个 vector 对应XxxCreateXxxVector(b_, v_)每个 struct 对应CreateVec3(b_, x, y, z)内部调用b_.Prep、b_.PrependFloat32等原语monster_generated.lobster根对象入口def GetRootAsMonster(buf:string): Monster { buf, buf.flatbuffers_indirect(0) }从缓冲起始位置间接寻址得到根 tablemonster_generated.lobster。在 Lobster 中读取 FlatBuffer 二进制关联文档给出了读取的最简流程先引入库与生成代码把 FlatBuffer 二进制文件读入字符串再交给GetRootAsMonsterinclude monster_generated.lobster let fb read_file(monsterdata_test.mon) assert fb let monster MyGame_Example_GetRootAsMonster(fb)得到根对象后即可访问字段let hp monster.hp let pos monster.pos值得强调的设计点是hp与pos本质上是在字符串缓冲区上原地访问数据的函数但通过 Lobster 的 struct 方法语法调用方看到的体验与普通字段访问完全一致monster.hp、monster.pos。这得益于生成代码中flatbuffers_handle类型把缓冲区 偏移封装为句柄flatbuffers_field_*系列运行时原语完成 vtable 查找与默认值回退——例如def hp(): buf_.flatbuffers_field_int16(pos_, 8, 100)中第三个参数100就是 schema 中定义的默认值monster_generated.lobster。读取向量、union 等复合字段同样直观// 向量长度与按索引访问 for(monster.weapons_length) i: assert monster.weapons(i).name weapon_names[i] assert monster.weapons(i).damage weapon_damages[i] // union先取类型再按类型安全转型 assert monster.equipped_type() MyGame_Sample_Equipment_Weapon let union_weapon monster.equipped_as_Weapon assert union_weapon.name Axe完整可运行的读取与断言示例见 sample_binary.lobster。在 Lobster 中构造并写出 FlatBuffer读取之外Lobster 绑定同样完整支持写入。以 sample_binary.lobster 为例写入流程分为五步1. 创建 builderlet b flatbuffers_builder {}2. 构造嵌套对象武器表 字符串 向量let weapon_offsets : map(weapon_names) name, i: let ns b.CreateString(name) b.MyGame_Sample_WeaponStart() b.MyGame_Sample_WeaponAddName(ns) b.MyGame_Sample_WeaponAddDamage(weapon_damages[i]) b.MyGame_Sample_WeaponEnd() let weapons b.MyGame_Sample_MonsterCreateWeaponsVector(weapon_offsets) let name b.CreateString(Orc) let inv b.MyGame_Sample_MonsterCreateInventoryVector(map(10): _)3. 组装根对象b.MyGame_Sample_MonsterStart() b.MyGame_Sample_MonsterAddPos(b.MyGame_Sample_CreateVec3(1.0, 2.0, 3.0)) b.MyGame_Sample_MonsterAddHp(300) b.MyGame_Sample_MonsterAddName(name) b.MyGame_Sample_MonsterAddInventory(inv) b.MyGame_Sample_MonsterAddColor(MyGame_Sample_Color_Red) b.MyGame_Sample_MonsterAddWeapons(weapons) b.MyGame_Sample_MonsterAddEquippedType(MyGame_Sample_Equipment_Weapon) b.MyGame_Sample_MonsterAddEquipped(weapon_offsets[1]) let orc b.MyGame_Sample_MonsterEnd()4. 收尾Finish并取得可持久化/可传输的缓冲b.Finish(orc) let buf b.SizedCopy()5. 读回验证与读取流程一致MyGame_Sample_GetRootAsMonster(buf)即可直接访问。示例中特别验证了未显式赋值的mana字段会回退到默认值 150sample_binary.lobster说明写入侧的PrependInt16Slot(1, mana, 150)与读取侧的默认值机制是成对设计的。JSON 与 FlatBuffer 双向转换Lobster 绑定完整支持把 JSON 解析为 FlatBuffer以及把 FlatBuffer 生成 JSON。运行时提供两个顶层函数flatbuffers_json_to_binary(schema, json, includedirs)JSON → 二进制flatbuffers_binary_to_json(schema, fb, includedirs)二进制 → JSON两者都需要传入 schema 文本includedirs用于指定include引用的搜索目录可传空列表[]。仓库内的 sample_text.lobster 演示了完整的往返流程include from ../lobster/ include monster_generated.lobster // 读取 schema 与 JSON 数据 schema : read_file(monster.fbs, true) json : read_file(monsterdata.json, true) assert schema and json // JSON → 二进制 fb, err1 : flatbuffers_json_to_binary(schema, json, []) assert not err1 // 访问字段验证解析正确性 let monster MyGame_Sample_GetRootAsMonster(fb) assert monster.name Orc // 二进制 → JSON往返后应与原 JSON 完全一致 json2, err2 : flatbuffers_binary_to_json(schema, fb, []) assert not err2 assert json json2 print json这一往返断言assert json json2是对转换保真度的强验证。从文档描述与实现看该功能底层复用 C 的 JSON parser 与 generator因此在解析合规性与速度上都与 C 侧保持一致。速度特征Lobster 绑定之所以快源于两个设计原生二进制写入builder 原语Prep、PrependFloat32、StartVector、EndVector等直接利用 Lobster 对二进制值的原生支持无需中间表示vtable 原地访问读取侧通过flatbuffers_field_*直接做 vtable 查找与偏移解引用整个读取过程没有数据拷贝与对象反序列化。因此生成的访问器代码与运行时库都保持小而快的特性。文档同时提醒实际速度取决于 Lobster 的运行模式——以字节码 VM 执行还是编译为 C 执行性能会有差异对性能敏感的场景编译为 C 模式通常能获得更接近原生实现的吞吐。在 MNN 项目中的落点本指南所依托的3rd_party/flatbuffers是 MNN 的第三方序列化依赖。MNN 的模型与算子定义正是通过 FlatBuffers schema位于 schema/default编译生成 C 头文件位于 schema/current如MNN_generated.h、CaffeOp_generated.h、TensorflowOp_generated.h等供核心代码使用。虽然 MNN 运行时本身主要消费的是这些 C 绑定但 Lobster 绑定与 C 绑定共享同一套线格式规范与编译器实现理解本文的读取、构造、JSON 互转机制也就理解了 MNN 模型文件底层序列化格式的工作方式可作为阅读 Interpreter.cpp 等模型加载代码的预备知识。小结Lobster 绑定覆盖了 FlatBuffers 的核心能力面——flatc --lobster生成代码、flatbuffers_builder构造二进制、flatbuffers_handle零拷贝读取、以及基于 C parser/generator 的 JSON 双向转换。想要快速验证可直接在本仓库运行 sample_binary.lobster、sample_text.lobster 与 lobstertest.lobster需先按上文说明取得 Lobster 运行时与flatc生成代码。【免费下载链接】MNNMNN: A blazing-fast, lightweight inference engine battle-tested by Alibaba, powering high-performance on-device LLMs and Edge AI.项目地址: https://gitcode.com/GitHub_Trending/mn/MNN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 Lobster 中使用 FlatBuffers：MNN 仓库 3rd_party/flatbuffers 的读写与 JSON 互转实战指南
在 Lobster 中使用 FlatBuffersMNN 仓库 3rd_party/flatbuffers 的读写与 JSON 互转实战指南【免费下载链接】MNNMNN: A blazing-fast, lightweight inference engine battle-tested by Alibaba, powering high-performance on-device LLMs and Edge AI.项目地址: https://gitcode.com/GitHub_Trending/mn/MNN本指南以 MNN 仓库内置的 FlatBuffers 子模块3rd_party/flatbuffers中的 Lobster 语言绑定文档为核心系统讲解如何在 Lobster 语言中通过flatc --lobster生成代码、零拷贝读取 FlatBuffer 二进制、构造与写出二进制缓冲以及完成 JSON 与 FlatBuffers 双向转换。读完本文你将掌握 Lobster 场景下 FlatBuffers 从 schema 到读写、再到文本互转的完整链路并能直接复用仓库内samples与tests中的可运行示例进行验证。前置准备先掌握 FlatBuffers 基础在深入 Lobster 绑定的细节之前需要先具备 FlatBuffers 的通用基础。关联文档明确指出通用教程Tutorial页包含了对所有受支持语言含 Lobster的完整使用指南本页只讨论 Lobster 特有的细节。因此动手之前应当熟悉以下内容构建flatcFlatBuffers 模式编译器schema compiler使用 schema 编译器掌握flatc的命令行选项与代码生成流程编写 schema理解.fbs文件中的table、struct、enum、union、vector等核心概念。本仓库内的 monster.fbs 是贯穿本文全部示例的 schema它定义了Vec3struct、Weapontable、Monstertable、Color与Equipmentenum/union等类型是观察 Lobster 生成代码与运行时行为的最佳标本。此外monsterdata.json 提供了对应的 JSON 形态数据monsterdata_test.mon 则是测试用的二进制线格式文件。Lobster 库代码与测试代码的位置库代码位置FlatBuffers 的 Lobster 运行时库代码位于 FlatBuffers 源码树的lobster/目录。需要注意当前仓库的实际情况MNN 的3rd_party/flatbuffers以第三方依赖形式内嵌其顶层目录CMake、docs、grpc、include、reflection、samples、src、tests等中并未包含lobster/运行时目录即flatbuffers.lobster运行时文件需要从 Lobster / FlatBuffers 官方源获取。仓库中保留的是与 Lobster 相关的示例、生成代码与测试它们通过include from ../lobster/与include flatbuffers.lobster见 sample_binary.lobster引用该运行时。测试代码与运行方式Lobster 绑定的测试代码位于 FlatBuffers 的tests/目录本仓库对应的文件是 lobstertest.lobster配套的生成代码为 monster_test_generated.lobster。运行测试的方式很简单lobster lobstertest.lobsterLobster 语言本身需从其官方主页或 GitHub 仓库获取并针对你的平台完成构建。运行环境上Lobster 既可作为字节码 VM 解释执行也可编译为 C 后执行这一点直接影响性能表现详见后文速度一节。从源码看lobstertest.lobster的测试覆盖了三个关键场景读取规范的二进制文件read_file(monsterdata_test.mon)读入由 C 实现产出的线格式数据再交给生成的MyGame_Example_GetRootAsMonster解析并逐字段断言lobstertest.lobster用生成代码构造二进制通过flatbuffers_builder配合生成的MonsterStart / MonsterAdd* / MonsterEnd系列函数自建 Monster 对象再调用check_read_buffer校验并把结果写回monsterdata_lobster_wire.monlobstertest.lobsterJSON 往返测试二进制转 JSON、JSON 再转二进制最终仍通过check_read_buffer验证内容一致lobstertest.lobster。由此可见Lobster 绑定在读写两个方向上都与 C 侧产出的线格式完全互通。生成 Lobster 代码flatc 的 --lobster 选项在 Lobster 中读写 FlatBuffer 的第一步是用flatc从 schema 生成 Lobster 类flatc --lobster monster.fbs--lobster选项在编译器主入口 flatc_main.cpp 中注册对应实现位于 idl_gen_lobster.cpp。生成的.lobster文件如 monster_generated.lobster以// automatically generated by the FlatBuffers compiler, do not modify开头结构上包含四类产物命名空间与枚举namespace MyGame_Sample把生成的符号归入统一前缀enum 声明Color_Red、Equipment_Weapon等常量struct 占位声明struct Vec3/struct Monster/struct Weapon先声明、后定义读取访问器struct Vec3 : flatbuffers_handle中定义x()、y()、z()通过buf_.read_float32_le(pos_ 0)直接按偏移读取内存struct Monster : flatbuffers_handle中定义pos()、hp()、name()、inventory(i)、weapons(i)、equipped_as_Weapon()等字段访问器monster_generated.lobster写入辅助函数每个 table 对应XxxStart()、XxxAddField(...)、XxxEnd()每个 vector 对应XxxCreateXxxVector(b_, v_)每个 struct 对应CreateVec3(b_, x, y, z)内部调用b_.Prep、b_.PrependFloat32等原语monster_generated.lobster根对象入口def GetRootAsMonster(buf:string): Monster { buf, buf.flatbuffers_indirect(0) }从缓冲起始位置间接寻址得到根 tablemonster_generated.lobster。在 Lobster 中读取 FlatBuffer 二进制关联文档给出了读取的最简流程先引入库与生成代码把 FlatBuffer 二进制文件读入字符串再交给GetRootAsMonsterinclude monster_generated.lobster let fb read_file(monsterdata_test.mon) assert fb let monster MyGame_Example_GetRootAsMonster(fb)得到根对象后即可访问字段let hp monster.hp let pos monster.pos值得强调的设计点是hp与pos本质上是在字符串缓冲区上原地访问数据的函数但通过 Lobster 的 struct 方法语法调用方看到的体验与普通字段访问完全一致monster.hp、monster.pos。这得益于生成代码中flatbuffers_handle类型把缓冲区 偏移封装为句柄flatbuffers_field_*系列运行时原语完成 vtable 查找与默认值回退——例如def hp(): buf_.flatbuffers_field_int16(pos_, 8, 100)中第三个参数100就是 schema 中定义的默认值monster_generated.lobster。读取向量、union 等复合字段同样直观// 向量长度与按索引访问 for(monster.weapons_length) i: assert monster.weapons(i).name weapon_names[i] assert monster.weapons(i).damage weapon_damages[i] // union先取类型再按类型安全转型 assert monster.equipped_type() MyGame_Sample_Equipment_Weapon let union_weapon monster.equipped_as_Weapon assert union_weapon.name Axe完整可运行的读取与断言示例见 sample_binary.lobster。在 Lobster 中构造并写出 FlatBuffer读取之外Lobster 绑定同样完整支持写入。以 sample_binary.lobster 为例写入流程分为五步1. 创建 builderlet b flatbuffers_builder {}2. 构造嵌套对象武器表 字符串 向量let weapon_offsets : map(weapon_names) name, i: let ns b.CreateString(name) b.MyGame_Sample_WeaponStart() b.MyGame_Sample_WeaponAddName(ns) b.MyGame_Sample_WeaponAddDamage(weapon_damages[i]) b.MyGame_Sample_WeaponEnd() let weapons b.MyGame_Sample_MonsterCreateWeaponsVector(weapon_offsets) let name b.CreateString(Orc) let inv b.MyGame_Sample_MonsterCreateInventoryVector(map(10): _)3. 组装根对象b.MyGame_Sample_MonsterStart() b.MyGame_Sample_MonsterAddPos(b.MyGame_Sample_CreateVec3(1.0, 2.0, 3.0)) b.MyGame_Sample_MonsterAddHp(300) b.MyGame_Sample_MonsterAddName(name) b.MyGame_Sample_MonsterAddInventory(inv) b.MyGame_Sample_MonsterAddColor(MyGame_Sample_Color_Red) b.MyGame_Sample_MonsterAddWeapons(weapons) b.MyGame_Sample_MonsterAddEquippedType(MyGame_Sample_Equipment_Weapon) b.MyGame_Sample_MonsterAddEquipped(weapon_offsets[1]) let orc b.MyGame_Sample_MonsterEnd()4. 收尾Finish并取得可持久化/可传输的缓冲b.Finish(orc) let buf b.SizedCopy()5. 读回验证与读取流程一致MyGame_Sample_GetRootAsMonster(buf)即可直接访问。示例中特别验证了未显式赋值的mana字段会回退到默认值 150sample_binary.lobster说明写入侧的PrependInt16Slot(1, mana, 150)与读取侧的默认值机制是成对设计的。JSON 与 FlatBuffer 双向转换Lobster 绑定完整支持把 JSON 解析为 FlatBuffer以及把 FlatBuffer 生成 JSON。运行时提供两个顶层函数flatbuffers_json_to_binary(schema, json, includedirs)JSON → 二进制flatbuffers_binary_to_json(schema, fb, includedirs)二进制 → JSON两者都需要传入 schema 文本includedirs用于指定include引用的搜索目录可传空列表[]。仓库内的 sample_text.lobster 演示了完整的往返流程include from ../lobster/ include monster_generated.lobster // 读取 schema 与 JSON 数据 schema : read_file(monster.fbs, true) json : read_file(monsterdata.json, true) assert schema and json // JSON → 二进制 fb, err1 : flatbuffers_json_to_binary(schema, json, []) assert not err1 // 访问字段验证解析正确性 let monster MyGame_Sample_GetRootAsMonster(fb) assert monster.name Orc // 二进制 → JSON往返后应与原 JSON 完全一致 json2, err2 : flatbuffers_binary_to_json(schema, fb, []) assert not err2 assert json json2 print json这一往返断言assert json json2是对转换保真度的强验证。从文档描述与实现看该功能底层复用 C 的 JSON parser 与 generator因此在解析合规性与速度上都与 C 侧保持一致。速度特征Lobster 绑定之所以快源于两个设计原生二进制写入builder 原语Prep、PrependFloat32、StartVector、EndVector等直接利用 Lobster 对二进制值的原生支持无需中间表示vtable 原地访问读取侧通过flatbuffers_field_*直接做 vtable 查找与偏移解引用整个读取过程没有数据拷贝与对象反序列化。因此生成的访问器代码与运行时库都保持小而快的特性。文档同时提醒实际速度取决于 Lobster 的运行模式——以字节码 VM 执行还是编译为 C 执行性能会有差异对性能敏感的场景编译为 C 模式通常能获得更接近原生实现的吞吐。在 MNN 项目中的落点本指南所依托的3rd_party/flatbuffers是 MNN 的第三方序列化依赖。MNN 的模型与算子定义正是通过 FlatBuffers schema位于 schema/default编译生成 C 头文件位于 schema/current如MNN_generated.h、CaffeOp_generated.h、TensorflowOp_generated.h等供核心代码使用。虽然 MNN 运行时本身主要消费的是这些 C 绑定但 Lobster 绑定与 C 绑定共享同一套线格式规范与编译器实现理解本文的读取、构造、JSON 互转机制也就理解了 MNN 模型文件底层序列化格式的工作方式可作为阅读 Interpreter.cpp 等模型加载代码的预备知识。小结Lobster 绑定覆盖了 FlatBuffers 的核心能力面——flatc --lobster生成代码、flatbuffers_builder构造二进制、flatbuffers_handle零拷贝读取、以及基于 C parser/generator 的 JSON 双向转换。想要快速验证可直接在本仓库运行 sample_binary.lobster、sample_text.lobster 与 lobstertest.lobster需先按上文说明取得 Lobster 运行时与flatc生成代码。【免费下载链接】MNNMNN: A blazing-fast, lightweight inference engine battle-tested by Alibaba, powering high-performance on-device LLMs and Edge AI.项目地址: https://gitcode.com/GitHub_Trending/mn/MNN创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
