Crate ggus 

# ggus

ggus 是一个高性能的 Rust 实现的 GGUF (GGML Unified Format) 文件格式处理库。

项目简介

GGUF 是一种用于存储大型语言模型权重和元数据的文件格式，提出于 llama.cpp 项目。

该库提供了全面的 API 用于读取、解析、修改和创建 GGUF 文件，支持所有 GGUF 规范中定义的数据类型和元数据。ggus 以 Rust 的安全性、性能和并发能力为基础，为 LLM 模型的部署和管理提供了可靠的工具。

更多细节请参考 GGUF 的官方规范。

主要特性

该库的核心功能和特性包括：

• 完整支持 GGUF 文件格式的读取和写入；
• 高效的内存管理和数据访问；
• 丰富的元数据处理功能；
• 张量数据的便捷访问；
• 严格的类型检查和错误处理；
• 零拷贝设计，最小化内存占用；
• 完全兼容 GGML 生态系统；

使用示例

下面的示例展示了创建并写入 GGUF 文件、读取 GGUF 文件头的过程：

use ggus::{
    DataFuture, GGufFileHeader, GGufFileWriter, GGufMetaDataValueType, GGufTensorWriter, GGmlType,
    GGufReader, GGufReadError,
};
use std::fs::File;
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ========== 写入部分 ==========
    let file = File::create("new_model.gguf")?;
    let header = GGufFileHeader::new(3, 0, 0);

    let mut writer = GGufFileWriter::new(file, header)?;

    // 写入元数据
    writer.write_alignment(32)?;
    writer.write_meta_kv("general.architecture", GGufMetaDataValueType::String, b"llama\0")?;
    writer.write_meta_kv("general.name", GGufMetaDataValueType::String, b"My Model\0")?;
    writer.write_meta_kv("llm.context_length", GGufMetaDataValueType::U32, &2048u32.to_le_bytes())?;

    // 写入张量
    let mut tensor_writer = writer.finish::<Vec<u8>>(true);
    let shape = [4, 4];
    let data_bytes = vec![
        1u8, 0, 0, 0,   // f32 = 1.0 little endian
        0, 0, 128, 63,  // f32 = 1.0
        0, 0, 0, 64,    // f32 = 2.0
        0, 0, 64, 64,   // f32 = 3.0
        0, 0, 128, 64,  // f32 = 4.0
        0, 0, 160, 64,  // f32 = 5.0
        0, 0, 176, 64,  // f32 = 6.0
        0, 0, 192, 64,  // f32 = 8.0
        0, 0, 208, 64,  // f32 = 6.5
        0, 0, 224, 64,  // f32 = 7.0
        0, 0, 240, 64,  // f32 = 7.5
        0, 0, 0, 65,    // f32 = 8.0
        0, 0, 16, 65,   // f32 = 9.0
        0, 0, 32, 65,   // f32 = 10.0
        0, 0, 48, 65,   // f32 = 11.0
        0, 0, 64, 65,   // f32 = 12.0
    ];

    tensor_writer.write_tensor("weight", GGmlType::F32, &shape, data_bytes)?;
    tensor_writer.finish()?;

    // ========== 读取部分 ==========
    let data = std::fs::read("new_model.gguf")?;
    let file_name = std::path::Path::new("new_model.gguf").file_name().unwrap().to_str().unwrap();
    println!("文件名: {file_name}\n");

    let mut reader = GGufReader::new(&data);
    let header = match reader.read_header() {
        Ok(h) => h,
        Err(e) => {
            eprintln!("读取 GGUF 头失败: {:?}", e);
            return Err(Box::new(std::io::Error::new(
                std::io::ErrorKind::Other,
                "读取 GGUF 头失败",
            )));
        }
    };

    println!(
        "字节序: {}",
        if header.is_native_endian() {
            "Native"
        } else {
            "Swapped"
        }
    );
    println!("版本号: {}", header.version);
    println!("元数据键值对数量: {}", header.metadata_kv_count);
    println!("张量数量: {}", header.tensor_count);

    Ok(())
}

更详细的示例可以参考示例代码，它展示了如何打印 GGUF 文件的内容。

应用场景

ggus 库适用于以下场景：

1. LLM 模型部署工具：用于构建加载、转换和优化 LLM 模型的工具；
2. 模型格式转换：在不同的模型格式之间进行转换，如 PyTorch/Safetensors 到 GGUF；
3. 量化工具：为模型参数实现不同的量化策略；
4. 模型检查和分析：检查模型结构和权重；
5. 自定义 LLM 推理引擎：为 Rust 编写的推理引擎提供模型加载功能；
6. 模型合并和裁剪：合并多个模型或移除不必要的层；

Re-exports

pub extern crate ggml_quants;

Structs

GGmlTypeSize

GGML 数据类型的大小和块大小。

GGuf

GGUF 文件的主要结构体，包含文件头、元数据键值对、张量元数据和实际数据。

GGufExtNotMatch

错误类型，表示 GGUF 文件名不符合预期的扩展名。

GGufFileHeader

GGufFileHeader 定义 GGUF 文件头结构。

GGufFileName

GGufFileName 定义 GGUF 文件名的结构。

GGufFileSimulator

简化的 GGUF 文件模拟器。

GGufFileWriter

简化的 GGUF 文件写入器，负责将 GGUF 文件头和元数据写入到文件中。

GGufMetaKV

GGufMetaKV 结构体表示 GGUF 文件中的元数据键值对。

GGufMetaValueArray

GGufMetaValueArray 结构体表示 GGUF 文件中元数据值的数组。

GGufReader

GGufReader 定义读取 GGUF 文件的读取器。

GGufTensorInfo

GGufTensorInfo 结构体表示 GGUF 文件中的张量信息。

GGufTensorMeta

GGufTensorMeta 结构体表示 GGUF 文件中的张量元数据。

GGufTensorSimulator

完整的 GGUF 文件模拟器。

GGufTensorWriter

完整的 GGUF 张量写入器，负责将张量数据写入到 GGUF 文件中。

GGufWriter

GGufWriter 用于写入 GGUF 文件格式的数据。

Enums

GGmlTokenType

枚举 GGML 中的不同 token 类型。

GGmlType

GGML tencor 数据类型。

GGufError

GGUF 文件解析时可能遇到的错误类型。

GGufFileType

GGUF 文件类型枚举。

GGufMetaDataValueType

GGufMetaError

GGufMetaError 枚举定义了 GGUF 元数据键值对获取时可能出现的错误。

GGufReadError

GGufReadError 定义 GGUF 读取器可能遇到的错误。

Constants

DEFAULT_ALIGNMENT

默认对齐方式。

GENERAL_ALIGNMENT

表示对齐方式的键。

Traits

DataFuture

Trait 用于获取数据的未来值，允许从不同类型中获取字节切片。

GGufMetaMap

GGufMetaMap trait 定义了获取 GGUF 元数据键值对的接口。

GGufMetaMapExt

GGufMetaMapExt trait 扩展了 GGufMetaMap，提供了各种类型的元数据键值对获取函数。