ggus

https://docs.rs/ggus/0.5.1/
Admin
ggus is a high-performance Rust library for reading, parsing, modifying, and creating GGUF files,...
Tokens:38,480
Snippets:167
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Create and Read GGUF Files

Source: https://docs.rs/ggus/0.5.1/ggus/index.html

Demonstrates the process of creating a GGUF file with metadata and tensors, followed by reading and inspecting the file header.

```rust
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(())
}
```

--------------------------------

### Get written bytes

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGufTensorSimulator.html

Method to retrieve the total number of bytes written to the simulator.

```rust
pub fn written_bytes(&self) -> usize
```

--------------------------------

### GGufMetaMap Trait Definition

Source: https://docs.rs/ggus/0.5.1/ggus/trait.GGufMetaMap.html

The core trait definition for accessing GGUF metadata, requiring implementation of the get method.

```rust
pub trait GGufMetaMap {
    // Required method
    fn get(&self, key: &str) -> Option<(Ty, &[u8])>;
}
```

--------------------------------

### GGufMetaKV Methods

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGufMetaKV.html

Methods for creating instances and accessing metadata properties.

```rust
pub const unsafe fn new_unchecked(data: &'a [u8]) -> Self
```

```rust
pub fn new(data: &'a [u8]) -> Result<Self, GGufReadError>
```

```rust
pub fn key(&self) -> &'a str
```

```rust
pub fn ty(&self) -> Ty
```

```rust
pub fn value_bytes(&self) -> &'a [u8] ⓘ
```

```rust
pub fn value_reader(&self) -> GGufReader<'a>
```

```rust
pub fn read_integer(&self) -> isize
```

```rust
pub fn read_unsigned(&self) -> usize
```

--------------------------------

### DataFuture Trait Definition

Source: https://docs.rs/ggus/0.5.1/ggus/trait.DataFuture.html

The core trait definition requiring the implementation of the get method to return a byte slice.

```rust
pub trait DataFuture {
    // Required method
    fn get(&self) -> &[u8] ⓘ;
}
```

--------------------------------

### Test General Additional Metadata Fields

Source: https://docs.rs/ggus/0.5.1/src/ggus/metadata/collection.rs.html

Demonstrates how to populate a HashMap with various general metadata fields to test successful retrieval.

```rust
#[test]
fn test_general_additional_fields() {
    // 创建一个包含所有 general 字段的测试数据
    let mut map = HashMap::new();

    // 基本 general 字段
    map.insert(
        "general.architecture".to_string(),
        (Ty::String, encode_string("llama")),
    );
    map.insert(
        "general.name".to_string(),
        (Ty::String, encode_string("TestModel")),
    );
    map.insert(
        "general.author".to_string(),
        (Ty::String, encode_string("Test Author")),
    );

    // 添加额外的 general 字段
    map.insert(
        "general.organization".to_string(),
        (Ty::String, encode_string("TestOrg")),
    );
    map.insert(
        "general.basename".to_string(),
        (Ty::String, encode_string("base_model")),
    );
    map.insert(
        "general.quantized_by".to_string(),
        (Ty::String, encode_string("quantizer")),
    );
    map.insert(
        "general.license".to_string(),
        (Ty::String, encode_string("MIT")),
    );
    map.insert(
        "general.license.name".to_string(),
        (Ty::String, encode_string("MIT License")),
    );
    map.insert(
        "general.license.link".to_string(),
        (Ty::String, encode_string("https://mit-license.org")),
    );
    map.insert(
        "general.url".to_string(),
        (Ty::String, encode_string("https://example.com/model")),
    );
    map.insert(
        "general.doi".to_string(),
        (Ty::String, encode_string("10.1234/test")),
    );
    map.insert(
        "general.uuid".to_string(),
        (
            Ty::String,
            encode_string("123e4567-e89b-12d3-a456-426614174000"),
        ),
    );
    map.insert(
        "general.repo_url".to_string(),
        (Ty::String, encode_string("https://github.com/example/repo")),
    );
    map.insert("general.filetype".to_string(), (Ty::U32, encode_u32(0)));

    // source 相关字段
    map.insert(
        "general.source.url".to_string(),
        (Ty::String, encode_string("https://example.com/source")),
    );
    map.insert(
        "general.source.doi".to_string(),
        (Ty::String, encode_string("10.1234/source")),
    );
    map.insert(
        "general.source.uuid".to_string(),
        (
            Ty::String,
            encode_string("123e4567-e89b-12d3-a456-426614174001"),
        ),
    );
    map.insert(
        "general.source.repo_url".to_string(),
        (
            Ty::String,
            encode_string("https://github.com/example/source"),
        ),
    );

    // base_model 相关字段
    map.insert(
        "general.base_model.count".to_string(),
        (Ty::U32, encode_u32(2)),
    );
    map.insert(
        "general.base_model.0.name".to_string(),
        (Ty::String, encode_string("Base Model 1")),
    );
    map.insert(
        "general.base_model.0.author".to_string(),
        (Ty::String, encode_string("Base Author 1")),
    );
    map.insert(
        "general.base_model.0.version".to_string(),
        (Ty::String, encode_string("1.0")),
    );
    map.insert(
        "general.base_model.0.organization".to_string(),
        (Ty::String, encode_string("Base Org 1")),
    );
```

--------------------------------

### GGufReader::new

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGufReader.html

Creates a new instance of GGufReader from a byte slice.

```APIDOC
## pub const fn new(data: &'a [u8]) -> Self

### Description
Creates a new GGufReader instance to read from the provided byte slice.

### Parameters
- **data** (&[u8]) - Required - The byte slice containing GGUF data.
```

--------------------------------

### Simulator Testing

Source: https://docs.rs/ggus/0.5.1/src/ggus/write/simulator.rs.html

Unit tests demonstrating the usage of the simulator to calculate file sizes.

```rust
#[test]
fn test_simulator() {
    // 测试默认构造
    let mut sim = GGufFileSimulator::new();
    sim.write_meta_kv("test_key", GGufMetaDataValueType::String, b"test_value");
    sim.write_alignment(16);
    let mut tensor_sim = sim.finish();
    tensor_sim.write_tensor("test_tensor", GGmlType::F32, &[2, 2]);
    assert_eq!(tensor_sim.written_bytes(), 160);

    // 测试 default 构造函数
    let sim_default = GGufFileSimulator::default();
    assert_eq!(sim_default.alignment, DEFAULT_ALIGNMENT);

    // 测试 with_alignment 构造函数
    let sim2 = GGufFileSimulator::with_alignment(32);
    assert_eq!(sim2.alignment, 32);

    // 测试 flush 方法不会 panic
    let mut writer = NWrite;
    writer.flush().unwrap();
}
```

--------------------------------

### GGufTensorMeta::new

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGufTensorMeta.html

Creates a new GGufTensorMeta instance from a byte slice.

```APIDOC
## pub fn new(data: &'a [u8]) -> Result<Self, GGufReadError>

### Description
Creates a new `GGufTensorMeta` instance from the provided byte slice containing GGUF tensor metadata.

### Parameters
- **data** (&[u8]) - Required - A byte slice containing the raw GGUF tensor metadata.
```

--------------------------------

### Test Tensor Writer Initialization

Source: https://docs.rs/ggus/0.5.1/src/ggus/write/file_writer.rs.html

Verifies the transition from metadata writing to tensor writing and ensures alignment is correctly passed.

```rust
    #[test]
    fn test_finish_and_tensor_writer() {
        // 测试完成元数据写入并转换为张量写入器
        let cursor = Cursor::new(Vec::new());
        let writer = GGufFileWriter::new(cursor, create_test_header()).unwrap();

        // 创建张量写入器，不实际写入数据
        let tensor_writer = writer.finish::<Vec<u8>>(false);

        // 验证对齐值被正确传递
        assert_eq!(tensor_writer.alignment, DEFAULT_ALIGNMENT);
        assert_eq!(tensor_writer.offset, 0);
        assert!(tensor_writer.data.is_empty());
        assert!(!tensor_writer.write_data);
    }
```

--------------------------------

### GGufFileHeader::new

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGufFileHeader.html

Creates a new instance of the GGufFileHeader struct.

```APIDOC
## pub const fn new(version: u32, tensor_count: u64, metadata_kv_count: u64) -> Self

### Description
Creates a new GGufFileHeader instance with the specified version, tensor count, and metadata key-value count.

### Parameters
- **version** (u32) - The GGUF file version number.
- **tensor_count** (u64) - The number of tensors.
- **metadata_kv_count** (u64) - The number of metadata key-value pairs.
```

--------------------------------

### Test Metadata Key-Value Writing

Source: https://docs.rs/ggus/0.5.1/src/ggus/write/file_writer.rs.html

Demonstrates writing metadata key-value pairs and handling alignment updates, including panic scenarios for invalid types.

```rust
    #[test]
    fn test_write_meta_kv() {
        use std::panic::{AssertUnwindSafe, catch_unwind};

        // 测试写入元数据键值对
        let cursor = Cursor::new(Vec::new());
        let mut writer = GGufFileWriter::new(cursor, create_test_header()).unwrap();

        // 写入常规键值对
        writer
            .write_meta_kv("test.key", GGufMetaDataValueType::U32, &[1, 0, 0, 0])
            .unwrap();

        // 写入可能更改对齐值的键值对
        writer
            .write_meta_kv(
                "general.alignment",
                GGufMetaDataValueType::U32,
                &[64, 0, 0, 0],
            )
            .unwrap();

        // 对齐值应该被更新
        assert_eq!(writer.alignment, 64);

        // 写入非 u32 类型的键值对，触发 panic
        let result = catch_unwind(AssertUnwindSafe(|| {
            writer
                .write_meta_kv(
                    "general.alignment",
                    GGufMetaDataValueType::String,
                    b"test\0",
                )
                .unwrap();
        }));
        assert!(result.is_err(), "Expected panic for non-u32 value type");
    }
```

--------------------------------

### GGUF Simulator Implementation

Source: https://docs.rs/ggus/0.5.1/src/ggus/write/simulator.rs.html

Core structures and methods for simulating GGUF file and tensor writing processes.

```rust
use super::GGufWriter;
use crate::{DEFAULT_ALIGNMENT, GGmlType, GGufMetaDataValueType, pad};
use std::io::{Result, Write};

/// 简化的 GGUF 文件模拟器。
pub struct GGufFileSimulator {
    writer: GGufWriter<NWrite>,
    alignment: usize,
}

/// 完整的 GGUF 文件模拟器。
pub struct GGufTensorSimulator {
    writer: GGufWriter<NWrite>,
    alignment: usize,
    data: Vec<usize>,
    offset: usize,
}

impl Default for GGufFileSimulator {
    #[inline]
    fn default() -> Self {
        Self::new()
    }
}

impl GGufFileSimulator {
    /// 创建一个新的 GGUF 文件模拟器。
    #[inline]
    pub fn new() -> Self {
        let mut writer = GGufWriter::new(NWrite);
        writer.write_header(Default::default()).unwrap();
        Self {
            writer,
            alignment: DEFAULT_ALIGNMENT,
        }
    }

    /// 使用指定的对齐值创建一个新的 GGUF 文件模拟器。
    #[inline]
    pub fn with_alignment(alignment: usize) -> Self {
        let mut ans = Self::new();
        ans.write_alignment(alignment);
        ans
    }

    /// 写入新的对齐值，并更新内部状态。
    #[inline]
    pub fn write_alignment(&mut self, alignment: usize) {
        self.writer.write_alignment(alignment).unwrap();
        self.alignment = alignment;
    }

    /// 写入元数据键值对，如果键为 `general.alignment`，则更新对齐值。
    #[inline]
    pub fn write_meta_kv(&mut self, key: &str, ty: GGufMetaDataValueType, val: &[u8]) {
        if let Some(alignment) = self.writer.write_meta_kv(key, ty, val).unwrap() {
            self.alignment = alignment;
        }
    }

    /// 完成模拟器的构建，返回一个 [`GGufTensorSimulator`]。
    #[inline]
    pub fn finish(self) -> GGufTensorSimulator {
        GGufTensorSimulator {
            writer: self.writer,
            alignment: self.alignment,
            data: Vec::new(),
            offset: 0,
        }
    }
}

impl GGufTensorSimulator {
    /// 写入张量数据。
    pub fn write_tensor(&mut self, name: &str, ty: GGmlType, shape: &[u64]) {
        self.offset += pad(self.offset, self.alignment);
        self.writer
            .write_tensor_info(name, shape, ty, self.offset as _)
            .unwrap();

        let len = ty.size().elements_to_bytes(shape);
        self.offset += len;
        self.data.push(len);
    }

    /// 获取已写入的字节数。
    pub fn written_bytes(&self) -> usize {
        let mut total = self.writer.written_bytes();
        for len in &self.data {
            total += pad(total, self.alignment);
            total += len;
        }
        total
    }
}

struct NWrite;

impl Write for NWrite {
    #[inline(always)]
    fn write(&mut self, buf: &[u8]) -> Result<usize> {
        Ok(buf.len())
    }
    #[inline(always)]
    fn flush(&mut self) -> Result<()> {
        Ok(())
    }
}
```

--------------------------------

### Tokenizer Configuration Methods

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGuf.html

Methods for retrieving tokenizer-specific metadata and vocabulary settings.

```APIDOC
## Tokenizer Configuration Access

### Methods
- `tokenizer_ggml_model()`: Returns the GGML model identifier.
- `tokenizer_ggml_tokens()`: Returns the vocabulary tokens.
- `tokenizer_ggml_scores()`: Returns the token scores.
- `tokenizer_ggml_token_type()`: Returns the token types.
- `tokenizer_ggml_merges()`: Returns the merge rules.
- `tokenizer_ggml_added_tokens()`: Returns the added tokens.
- `tokenizer_ggml_bos_token_id()`: Returns the BOS token ID.
- `tokenizer_ggml_eos_token_id()`: Returns the EOS token ID.
- `tokenizer_ggml_unknown_token_id()`: Returns the unknown token ID.
- `tokenizer_ggml_separator_token_id()`: Returns the separator token ID.
- `tokenizer_ggml_padding_token_id()`: Returns the padding token ID.
- `tokenizer_rwkv_world()`: Returns the RWKV tokenizer vocabulary.
```

--------------------------------

### GGufFileWriter Methods

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGufFileWriter.html

Methods for initializing and interacting with the GGUF file writer.

```APIDOC
## pub fn new(writer: T, header: GGufFileHeader) -> Result<Self>

### Description
Creates a new GGufFileWriter instance, initializing the GGUF file header.

## pub fn with_alignment(writer: T, header: GGufFileHeader, alignment: usize) -> Result<Self>

### Description
Creates a GGufFileWriter instance with a specified alignment value.

## pub fn write_alignment(&mut self, alignment: usize) -> Result<()>

### Description
Writes a new alignment value and updates the internal state.

## pub fn write_meta_kv(&mut self, key: &str, ty: GGufMetaDataValueType, val: &[u8]) -> Result<()>

### Description
Writes a metadata key-value pair. If the key is 'general.alignment', the internal alignment value is updated.

## pub fn finish<U>(self, write_data: bool) -> GGufTensorWriter<T, U>

### Description
Completes the metadata writing process and returns a GGufTensorWriter instance.
```

--------------------------------

### TestMetaMap Implementation

Source: https://docs.rs/ggus/0.5.1/src/ggus/metadata/collection.rs.html

A mock implementation of GGufMetaMap used for unit testing metadata retrieval.

```rust
struct TestMetaMap {
        data: HashMap<String, (Ty, Vec<u8>)>,
    }

    impl TestMetaMap {
        fn new() -> Self {
            let mut map = HashMap::new();

            // 添加各种类型的测试数据

            // 通用字段
            map.insert(
                "general.architecture".to_string(),
                (Ty::String, encode_string("llama")),
            );
            map.insert(
                "general.name".to_string(),
                (Ty::String, encode_string("TestModel")),
            );
            map.insert(
                "general.author".to_string(),
                (Ty::String, encode_string("Test Author")),
            );
            map.insert(
                "general.version".to_string(),
                (Ty::String, encode_string("1.0")),
            );
            map.insert(
                "general.description".to_string(),
                (Ty::String, encode_string("Test Description")),
            );
            map.insert(
                "general.quantization_version".to_string(),
                (Ty::U32, encode_u32(2)),
            );
            map.insert("general.alignment".to_string(), (Ty::U32, encode_u32(32)));
            map.insert(
                "general.size_label".to_string(),
                (Ty::String, encode_string("7B")),
            );
            map.insert(
                "general.finetune".to_string(),
                (Ty::String, encode_string("chat")),
            );
            map.insert(
                "general.tags".to_string(),
                (Ty::Array, encode_string_array(&["tag1", "tag2"])),
            );
            map.insert(
                "general.languages".to_string(),
                (Ty::Array, encode_string_array(&["en", "zh"])),
            );

            // LLM 特定字段
            map.insert(
                "llama.context_length".to_string(),
                (Ty::U32, encode_u32(4096)),
            );
            map.insert(
                "llama.embedding_length".to_string(),
                (Ty::U32, encode_u32(4096)),
            );
```

--------------------------------

### Writing GGUF Metadata and Tensors

Source: https://docs.rs/ggus/0.5.1/src/ggus/write/file_writer.rs.html

Initializes a file writer, writes metadata, and appends tensors to the file.

```rust
// 创建文件写入器
let mut writer = GGufFileWriter::new(cursor, header).unwrap();

// 写入元数据
writer.write_alignment(64).unwrap();
writer
    .write_meta_kv(
        "general.architecture",
        GGufMetaDataValueType::String,
        b"llama\0",
    )
    .unwrap();
writer
    .write_meta_kv(
        "general.name",
        GGufMetaDataValueType::String,
        b"test_model\0",
    )
    .unwrap();
writer
    .write_meta_kv(
        "llm.context_length",
        GGufMetaDataValueType::U32,
        &4096u32.to_le_bytes(),
    )
    .unwrap();

// 完成元数据写入并创建张量写入器
let mut tensor_writer = writer.finish::<Vec<u8>>(true);

// 写入第一个张量
let shape1 = [5, 5];
let data1 = vec![0u8; 100]; // f32数据，每个元素4字节
tensor_writer
    .write_tensor("embeddings", GGmlType::F32, &shape1, data1)
    .unwrap();

// 写入第二个张量
let shape2 = [10, 20];
let data2 = vec![0u8; 400]; // f32数据
tensor_writer
    .write_tensor("weights", GGmlType::F32, &shape2, data2)
    .unwrap();

// 完成写入
let total_bytes = tensor_writer.finish().unwrap();

// 验证总写入字节数
assert!(total_bytes > 500); // 头部+元数据+两个张量+对齐填充
```

--------------------------------

### GGufFileHeader Implementation Methods

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGufFileHeader.html

Methods available on the GGufFileHeader struct for creating instances and validating header properties.

```rust
pub const fn new( version: u32, tensor_count: u64, metadata_kv_count: u64, ) -> Self
```

```rust
pub fn is_magic_correct(&self) -> bool
```

```rust
pub const fn is_native_endian(&self) -> bool
```

```rust
pub const fn magic(&self) -> Result<&str, Utf8Error>
```

--------------------------------

### Test End-to-End Write Process

Source: https://docs.rs/ggus/0.5.1/src/ggus/write/file_writer.rs.html

Initializes an end-to-end test for the full GGUF writing process.

```rust
    #[test]
    fn test_end_to_end_write_process() {
        // 端到端测试，完整的写入流程
        let cursor = Cursor::new(Vec::new());
        let header = GGufFileHeader::new(3, 0, 0);
```

--------------------------------

### GGuf::new

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGuf.html

Creates a new GGuf instance by parsing the provided raw byte data.

```APIDOC
## pub fn new(data: &'a [u8]) -> Result<Self, GGufError>

### Description
Creates a new `GGuf` instance, parsing the provided GGUF file data from a byte slice.

### Parameters
- **data** (&[u8]) - Required - The raw byte data of the GGUF file.

### Returns
- **Result<Self, GGufError>** - Returns a new `GGuf` instance on success, or a `GGufError` if parsing fails.
```

--------------------------------

### LLM Configuration Methods

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGuf.html

Methods for retrieving LLM architecture and attention mechanism parameters.

```APIDOC
## LLM Configuration Access

### Methods
- `llm_context_length()`: Returns the context length.
- `llm_embedding_length()`: Returns the embedding length.
- `llm_block_count()`: Returns the number of blocks.
- `llm_feed_forward_length()`: Returns the feed-forward layer length.
- `llm_use_parallel_residual()`: Returns whether parallel residual is used.
- `llm_tensor_data_layout()`: Returns the tensor data layout.
- `llm_expert_count()`: Returns the number of experts.
- `llm_expert_used_count()`: Returns the number of used experts.
- `llm_attention_head_count()`: Returns the number of attention heads.
- `llm_attention_head_count_kv()`: Returns the number of KV attention heads.
- `llm_attention_max_alibi_bias()`: Returns the maximum Alibi bias.
- `llm_attention_clamp_kqv()`: Returns the K/Q/V clamp threshold.
- `llm_attention_layer_norm_epsilon()`: Returns the layer norm epsilon.
- `llm_attention_layer_norm_rms_epsilon()`: Returns the RMS layer norm epsilon.
- `llm_attention_key_length()`: Returns the attention key length.
- `llm_attention_value_length()`: Returns the attention value length.
- `llm_rope_dimension_count()`: Returns the RoPE dimension count.
- `llm_rope_freq_base()`: Returns the RoPE frequency base.
- `llm_rope_scaling_type()`: Returns the RoPE scaling type.
- `llm_rope_scaling_factor()`: Returns the RoPE scaling factor.
- `llm_rope_scaling_original_context_length()`: Returns the original context length for RoPE scaling.
- `llm_rope_scaling_finetuned()`: Returns whether RoPE scaling is fine-tuned.
- `llm_rope_scale_linear()`: Returns the RoPE linear scaling factor.
- `llm_ssm_conv_kernel()`: Returns the SSM convolution kernel size.
- `llm_ssm_inner_size()`: Returns the SSM inner size.
- `llm_ssm_state_size()`: Returns the SSM state size.
- `llm_ssm_time_step_rank()`: Returns the SSM time step rank.
```

--------------------------------

### Create Mock GGUF Data for Testing

Source: https://docs.rs/ggus/0.5.1/src/ggus/file.rs.html

Helper functions to generate raw byte vectors representing valid or invalid GGUF file structures for unit testing.

```rust
fn create_duplicate_tensor_data() -> Vec<u8> {
    let mut data = Vec::new();

    // 添加文件头
    data.extend_from_slice(b"GGUF");
    data.extend_from_slice(&3u32.to_le_bytes());
    data.extend_from_slice(&2u64.to_le_bytes());
    data.extend_from_slice(&0u64.to_le_bytes());

    // 两个相同名称的张量
    for _ in 0..2 {
        let tensor_name = "duplicate_tensor";
        data.extend_from_slice(&(tensor_name.len() as u64).to_le_bytes());
        data.extend_from_slice(tensor_name.as_bytes());
        data.extend_from_slice(&1u32.to_le_bytes());
        data.extend_from_slice(&1u64.to_le_bytes());
        data.extend_from_slice(&(GGmlType::F32 as u32).to_le_bytes());
        data.extend_from_slice(&0u64.to_le_bytes());
    }

    data
}
```

```rust
fn create_invalid_alignment_type_data() -> Vec<u8> {
    let mut data = Vec::new();

    // 添加文件头
    data.extend_from_slice(b"GGUF");
    data.extend_from_slice(&3u32.to_le_bytes());
    data.extend_from_slice(&0u64.to_le_bytes());
    data.extend_from_slice(&1u64.to_le_bytes());

    // 使用不支持的类型作为 alignment
    let key = "general.alignment";
    data.extend_from_slice(&(key.len() as u64).to_le_bytes());
    data.extend_from_slice(key.as_bytes());
    data.extend_from_slice(&(GGufMetaDataValueType::String as u32).to_le_bytes());
    let value = "not_a_number\0";
    data.extend_from_slice(&(value.len() as u64).to_le_bytes());
    data.extend_from_slice(value.as_bytes());

    data
}
```

--------------------------------

### Metadata KV Test Utilities

Source: https://docs.rs/ggus/0.5.1/src/ggus/metadata/meta_kv.rs.html

Helper functions for constructing binary metadata key-value pairs and encoding various primitive types for testing purposes.

```rust
fn build_kv_data(key: &str, ty: Ty, value: &[u8]) -> Vec<u8> {
    let mut data = Vec::new();

    // 写入键
    let key_len = key.len() as u64;
    data.extend_from_slice(&key_len.to_le_bytes());
    data.extend_from_slice(key.as_bytes());

    // 写入类型
    let ty_val = ty as u32;
    data.extend_from_slice(&ty_val.to_le_bytes());

    // 写入值
    data.extend_from_slice(value);

    data
}

// 编码各种基础类型数据
fn encode_u64(value: u64) -> Vec<u8> {
    value.to_le_bytes().to_vec()
}

fn encode_i64(value: i64) -> Vec<u8> {
    value.to_le_bytes().to_vec()
}

fn encode_u32(value: u32) -> Vec<u8> {
    value.to_le_bytes().to_vec()
}

fn encode_i32(value: i32) -> Vec<u8> {
    value.to_le_bytes().to_vec()
}

fn encode_u16(value: u16) -> Vec<u8> {
    value.to_le_bytes().to_vec()
}

fn encode_i16(value: i16) -> Vec<u8> {
    value.to_le_bytes().to_vec()
}

fn encode_f32(value: f32) -> Vec<u8> {
    value.to_le_bytes().to_vec()
}

fn encode_f64(value: f64) -> Vec<u8> {
    value.to_le_bytes().to_vec()
}

fn encode_string(value: &str) -> Vec<u8> {
    let mut data = Vec::new();
    let str_len = value.len() as u64;
    data.extend_from_slice(&str_len.to_le_bytes());
    data.extend_from_slice(value.as_bytes());
    data
}

fn encode_bool(value: bool) -> Vec<u8> {
    vec![if value { 1 } else { 0 }]
}

fn encode_array_header(ty: Ty, len: usize) -> Vec<u8> {
    let mut data = Vec::new();
    let ty_val = ty as u32;
    data.extend_from_slice(&ty_val.to_le_bytes());
    data.extend_from_slice(&(len as u64).to_le_bytes());
    data
}
```

--------------------------------

### Test Float Value Reading

Source: https://docs.rs/ggus/0.5.1/src/ggus/metadata/meta_kv.rs.html

Demonstrates reading F32 and F64 floating-point values from GGUF metadata.

```rust
#[test]
    fn test_float_values() {
        // 测试浮点数类型的键值对
        let f32_value = 42.5f32;
        let f64_value = 123.456f64;

        // 构建测试数据并测试
        let f32_data = build_kv_data("f32_key", Ty::F32, &encode_f32(f32_value));
        let kv = GGufMetaKV::new(&f32_data).unwrap();
        assert_eq!(kv.ty(), Ty::F32);
        let mut reader = kv.value_reader();
        assert_eq!(reader.read::<f32>().unwrap(), f32_value);

        let f64_data = build_kv_data("f64_key", Ty::F64, &encode_f64(f64_value));
        let kv = GGufMetaKV::new(&f64_data).unwrap();
        assert_eq!(kv.ty(), Ty::F64);
        let mut reader = kv.value_reader();
        assert_eq!(reader.read::<f64>().unwrap(), f64_value);
    }
```

--------------------------------

### Implement GGUF Parsing Logic

Source: https://docs.rs/ggus/0.5.1/src/ggus/file.rs.html

The new method initializes a GGuf instance by reading and validating the header, metadata, and tensor information from the provided byte slice.

```rust
impl<'a> GGuf<'a> {
    /// 创建一个新的 [`GGuf`] 实例，解析给定的 GGUF 数据。
    pub fn new(data: &'a [u8]) -> Result<Self, GGufError> {
        use GGufError::*;

        let mut reader = GGufReader::new(data);

        let header = reader.read_header().map_err(Reading)?;
        if !header.is_magic_correct() {
            return Err(MagicMismatch);
        }
        if !header.is_native_endian() {
            return Err(EndianNotSupport);
        }
        if header.version != 3 {
            return Err(VersionNotSupport);
        }

        let mut alignment = DEFAULT_ALIGNMENT;
        let mut meta_kvs = IndexMap::with_capacity(header.metadata_kv_count as _);
        for _ in 0..header.metadata_kv_count {
            let kv = reader.read_meta_kv().map_err(Reading)?;
            let k = kv.key();
            if k == GENERAL_ALIGNMENT {
                type Ty = GGufMetaDataValueType;
                alignment = match kv.ty() {
                    Ty::U32 => kv.value_reader().read::<u32>().map_err(Reading)? as _,
                    Ty::U64 => kv.value_reader().read::<u64>().map_err(Reading)? as _,
                    ty => return Err(AlignmentTypeMismatch(ty)),
                }
            }
            if meta_kvs.insert(k, kv).is_some() {
                return Err(DuplicateMetaKey(k.into()));
            }
        }

        let mut data_len = 0;
        let mut tensors = IndexMap::with_capacity(header.tensor_count as _);
        for _ in 0..header.tensor_count {
            let tensor = reader.read_tensor_meta().map_err(Reading)?;
            let name = tensor.name();
            let info = tensor.to_info();
            let end = info.offset() + info.nbytes();
            if end > data_len {
                data_len = end;
            }
            if tensors.insert(name, tensor).is_some() {
                return Err(DuplicateTensorName(name.into()));
            }
        }

        let cursor = data.len() - reader.remaining().len();
        let padding = if tensors.is_empty() {
            0
        } else {
            pad(cursor, alignment)
        };
        reader.skip::<u8>(padding).map_err(Reading)?;
        let data = reader.remaining();
        let data = if data.len() == data_len {
            data
        } else {
            let padding = pad(data_len, alignment);
            if data.len() == data_len + padding {
                info!("unnecessary padding detected")
```

--------------------------------

### General Metadata Methods

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGuf.html

Methods for retrieving general source and base model information from the GGUF file.

```APIDOC
## General Metadata Access

### Methods
- `general_source_uuid()`: Returns the source UUID.
- `general_source_repo_url()`: Returns the source repository URL.
- `general_base_model_count()`: Returns the number of base models.
- `general_base_model_name(id: usize)`: Returns the name of the base model at the specified ID.
- `general_base_model_author(id: usize)`: Returns the author of the base model at the specified ID.
- `general_base_model_version(id: usize)`: Returns the version of the base model at the specified ID.
- `general_base_model_organization(id: usize)`: Returns the organization of the base model at the specified ID.
- `general_base_model_url(id: usize)`: Returns the URL of the base model at the specified ID.
- `general_base_model_doi(id: usize)`: Returns the DOI of the base model at the specified ID.
- `general_base_model_uuid(id: usize)`: Returns the UUID of the base model at the specified ID.
- `general_base_model_repo_url(id: usize)`: Returns the repository URL of the base model at the specified ID.
```

--------------------------------

### GGufTensorMeta::to_info

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGufTensorMeta.html

Converts the metadata into a GGufTensorInfo object.

```APIDOC
## pub fn to_info(&self) -> GGufTensorInfo

### Description
Converts the current `GGufTensorMeta` instance into a `GGufTensorInfo` object.
```

--------------------------------

### GGUF File and Tensor Writer Implementation

Source: https://docs.rs/ggus/0.5.1/src/ggus/write/file_writer.rs.html

Core structures for managing GGUF file writing, including metadata and tensor data serialization.

```rust
1use super::GGufWriter;
2use crate::{DEFAULT_ALIGNMENT, GGmlType, GGufFileHeader, GGufMetaDataValueType, pad};
3use log::trace;
4use std::{
5    borrow::Borrow,
6    io::{Result, Write},
7    time::Instant,
8};
9
10/// 简化的 GGUF 文件写入器，负责将 GGUF 文件头和元数据写入到文件中。
11pub struct GGufFileWriter<T: Write> {
12    writer: GGufWriter<T>,
13    alignment: usize,
14}
15
16/// 完整的 GGUF 张量写入器，负责将张量数据写入到 GGUF 文件中。
17pub struct GGufTensorWriter<T: Write, U> {
18    writer: GGufWriter<T>,
19    alignment: usize,
20    data: Vec<U>,
21    offset: usize,
22    write_data: bool,
23}
24
25/// Trait 用于获取数据的未来值，允许从不同类型中获取字节切片。
26pub trait DataFuture {
27    /// 获取数据的字节切片。
28    fn get(&self) -> &[u8];
29}
30
31impl<T: Borrow<[u8]>> DataFuture for T {
32    /// 将借用的字节切片转换为 &[u8]。
33    #[inline]
34    fn get(&self) -> &[u8] {
35        self.borrow()
36    }
37}
38
39impl<T: Write> GGufFileWriter<T> {
40    /// 创建一个新的 [`GGufFileWriter`] 实例，初始化 GGUF 文件头。
41    #[inline]
42    pub fn new(writer: T, header: GGufFileHeader) -> Result<Self> {
43        let mut writer = GGufWriter::new(writer);
44        writer.write_header(header)?;
45        Ok(Self {
46            writer,
47            alignment: DEFAULT_ALIGNMENT,
48        })
49    }
50
51    /// 使用指定的对齐值创建 [`GGufFileWriter`] 实例。
52    #[inline]
53    pub fn with_alignment(writer: T, header: GGufFileHeader, alignment: usize) -> Result<Self> {
54        let mut ans = Self::new(writer, header)?;
55        ans.write_alignment(alignment)?;
56        Ok(ans)
57    }
58
59    /// 写入新的对齐值，并更新内部状态。
60    #[inline]
61    pub fn write_alignment(&mut self, alignment: usize) -> Result<()> {
62        self.writer.write_alignment(alignment)?;
63        self.alignment = alignment;
64        Ok(())
65    }
66
67    /// 写入元数据键值对，如果键为 `general.alignment`，则更新对齐值。
68    #[inline]
69    pub fn write_meta_kv(
70        &mut self,
71        key: &str,
72        ty: GGufMetaDataValueType,
73        val: &[u8],
74    ) -> Result<()> {
75        if let Some(alignment) = self.writer.write_meta_kv(key, ty, val)? {
76            self.alignment = alignment;
77        }
78        Ok(())
79    }
80
81    /// 完成元数据写入，并返回一个 [`GGufTensorWriter`] 实例。
82    #[inline]
83    pub fn finish<U>(self, write_data: bool) -> GGufTensorWriter<T, U> {
84        GGufTensorWriter {
85            writer: self.writer,
86            alignment: self.alignment,
87            data: Vec::new(),
88            offset: 0,
89            write_data,
90        }
91    }
92}
93
94impl<T: Write, U: DataFuture> GGufTensorWriter<T, U> {
95    /// 写入张量数据。
96    pub fn write_tensor(&mut self, name: &str, ty: GGmlType, shape: &[u64], data: U) -> Result<()> {
97        self.offset += pad(self.offset, self.alignment);
98        self.writer
99            .write_tensor_info(name, shape, ty, self.offset as _)
100            .unwrap();
101
102        let len = ty.size().elements_to_bytes(shape);
103        self.offset += len;
104        if self.write_data {
105            self.data.push(data)
106        }
107        Ok(())
108    }
109
110    /// 完成张量写入，返回已写入的字节数。
111    pub fn finish(self) -> Result<usize> {
112        let Self {
113            mut writer,
114            alignment,
115            data,
116            ..
117        } = self;
118
119        let total = data.len().to_string();
120        let width = total.len();
121        for (i, data) in data.into_iter().enumerate() {
122            let t0 = Instant::now();
123            let data = data.get();
124            let t1 = Instant::now();
125            writer.write_padding(alignment)?;
126            writer.write_data(data)?;
127            let t2 = Instant::now();
128            trace!(
129                "data {i:>width$}/{total} size = {} bytes, calculate in {:?}, write in {:?}",
130                data.len(),
131                t1 - t0,
132                t2 - t1,
133            )
134        }
135        Ok(writer.written_bytes())
136    }
137}
```

--------------------------------

### GGUF File Writer Unit Tests

Source: https://docs.rs/ggus/0.5.1/src/ggus/write/file_writer.rs.html

Tests for verifying the initialization and alignment configuration of the GGufFileWriter.

```rust
140    use super::*;
141    use crate::GGufFileHeader;
142    use std::io::Cursor;
143
144    // 测试辅助函数，创建一个标准的文件头
145    fn create_test_header() -> GGufFileHeader {
146        GGufFileHeader::new(3, 0, 0)
147    }
148
149    #[test]
150    fn test_file_writer_new() {
151        // 测试基本创建功能
152        let cursor = Cursor::new(Vec::new());
153        let writer = GGufFileWriter::new(cursor, create_test_header()).unwrap();
154
155        // 确认默认对齐值
156        assert_eq!(writer.alignment, DEFAULT_ALIGNMENT);
157    }
158
159    #[test]
160    fn test_file_writer_with_alignment() {
161        // 测试使用自定义对齐值创建
162        let cursor = Cursor::new(Vec::new());
163        let alignment = 64;
164        let writer =
165            GGufFileWriter::with_alignment(cursor, create_test_header(), alignment).unwrap();
166
167        // 确认对齐值正确设置
```

--------------------------------

### GGufFileSimulator Definition

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGufFileSimulator.html

The primary structure definition for the GGUF file simulator.

```rust
pub struct GGufFileSimulator { /* private fields */ }
```

--------------------------------

### GGufMetaValueArray::new

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGufMetaValueArray.html

Creates a new instance of GGufMetaValueArray.

```APIDOC
## pub const fn new(reader: GGufReader<'a>, len: usize) -> Self

### Description
Creates a new `GGufMetaValueArray` instance using the provided reader and length.

### Parameters
- **reader** (GGufReader<'a>) - The reader instance for the GGUF file.
- **len** (usize) - The length of the array.
```

--------------------------------

### GGufReader Unit Tests

Source: https://docs.rs/ggus/0.5.1/src/ggus/read.rs.html

Unit tests verifying the basic read functionality and boolean parsing logic of the GGufReader.

```rust
94mod tests {
95    use super::*;
96
97    #[test]
98    fn test_read() {
99        let data: &[u8] = &[1, 2, 3, 4, 5];
100        let mut reader = GGufReader::new(data);
101        assert_eq!(reader.read::<u8>().unwrap(), 1);
102        assert_eq!(reader.read::<u8>().unwrap(), 2);
103        assert_eq!(reader.read::<u8>().unwrap(), 3);
104        assert_eq!(reader.read::<u8>().unwrap(), 4);
105        assert_eq!(reader.read::<u8>().unwrap(), 5);
106    }
107
108    #[test]
109    fn test_read_bool() {
110        let data: &[u8] = &[0, 1, 2];
111        let mut reader = GGufReader::new(data);
112        assert!(!reader.read_bool().unwrap());
113        assert!(reader.read_bool().unwrap());
114        assert!(matches!(reader.read_bool(), Err(GGufReadError::Bool(2))));
115    }
116}
```
Tokens:
Raw