### GGufFileSimulator API Documentation

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

Provides comprehensive API documentation for the GGufFileSimulator struct, covering its methods for initialization, setting alignment, writing alignment, and writing metadata key-value pairs. Includes method signatures, parameter descriptions, and return values.

```APIDOC
Struct GGufFileSimulator

Simplified GGUF file simulator.

Methods:

finish()
  - Completes the GGUF file writing process.
  - Signature: pub fn finish(&mut self)
  - Returns: () (Unit type)

new()
  - Creates a new GGUF file simulator.
  - Signature: pub fn new() -> Self
  - Returns: Self (An instance of GGufFileSimulator)

with_alignment(alignment: usize)
  - Creates a new GGUF file simulator with a specified alignment value.
  - Parameters:
    - alignment: The alignment value to set for the simulator.
  - Signature: pub fn with_alignment(alignment: usize) -> Self
  - Returns: Self (An instance of GGufFileSimulator)

write_alignment(alignment: usize)
  - Writes a new alignment value and updates the internal state.
  - Parameters:
    - alignment: The alignment value to write.
  - Signature: pub fn write_alignment(&mut self, alignment: usize)
  - Returns: ()

write_meta_kv(key: &str, value: &str)
  - Writes a key-value pair to the GGUF file's metadata.
  - Parameters:
    - key: The metadata key.
    - value: The metadata value.
  - Signature: pub fn write_meta_kv(&mut self, key: &str, value: &str)
  - Returns: ()

Related Methods:
  - new() and with_alignment() are used for initialization.
  - write_alignment() and write_meta_kv() are used for writing data.
  - finish() is used to finalize the file creation.
```

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

### Get GGML Tokenizer BOS Token ID (Rust)

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

Retrieves the Beginning-Of-Sequence (BOS) token ID (as u32) for the GGML tokenizer from GGuf metadata. This ID marks the start of a sequence.

```rust
    /// 获取 ggml 分词器的起始标记 ID。
    #[inline]
    fn tokenizer_ggml_bos_token_id(&self) -> Result<u32, GGufMetaError> {
        self.get_u32("tokenizer.ggml.bos_token_id")
    }
```

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

### Get Tokenizer GGML Vocabulary

Source: https://docs.rs/ggus/0.5.1/ggus/trait.GGufMetaMapExt

Retrieves the vocabulary (list of tokens) for the GGML tokenizer. This is an array of strings representing the tokens.

```rust
fn tokenizer_ggml_tokens(&self) -> Result<GGufMetaValueArray<'_, str>, GGufMetaError>
// Retrieves the vocabulary for the GGML tokenizer.
```

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

### Rust: End-to-end GGUF write process

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

Provides a high-level overview of the complete GGUF file writing process. It initializes a writer with a header and demonstrates the start of writing metadata, implying a full workflow from header creation to data serialization.

```Rust
use std::io::Cursor;
use gguf_rs::gguf_writer::{GGufFileWriter, GGufFileHeader};

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

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

    // 写入元数据
    // ... further operations like write_meta_kv, finish, write_tensor would follow ...
}
```

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

### Finish GGufTensorSimulator Construction

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

Completes the construction of the simulator and returns a GGufTensorSimulator instance.

```rust
pub fn finish(self) -> GGufTensorSimulator

完成模拟器的构建，返回一个 [`GGufTensorSimulator`]。
```

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

### Get Tokenizer GGML Scores

Source: https://docs.rs/ggus/0.5.1/ggus/trait.GGufMetaMapExt

Retrieves the scores associated with each token in the GGML tokenizer's vocabulary. This is an array of floating-point numbers.

```rust
fn tokenizer_ggml_scores(&self) -> Result<GGufMetaValueArray<'_, f32>, GGufMetaError>
// Retrieves the scores for the GGML tokenizer.
```

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

### Get LLM Attention Value Length (Rust)

Source: https://docs.rs/ggus/0.5.1/ggus/trait.GGufMetaMapExt

Retrieves the length of the attention value. Returns a Result with the value length as a usize or a GGufMetaError.

```rust
fn llm_attention_value_length(&self) -> Result<usize, GGufMetaError>

获取注意力 Value 长度。

Parameters:
  None

Returns:
  Result<usize, GGufMetaError>: The attention value length or an error.
```

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

### Create and Read GGUF File with Rust ggus

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

This example demonstrates creating a new GGUF file, writing metadata (architecture, name, context length) and tensor data (weights) using `GGufFileWriter`. It then shows how to read the file header and display its properties using `GGufReader`.

```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!("文件名: {}\n", file_name);

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

```

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

### Create and Read GGUF File with Rust ggus

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

This example demonstrates creating a new GGUF file, writing metadata (architecture, name, context length) and tensor data (weights) using `GGufFileWriter`. It then shows how to read the file header and display its properties using `GGufReader`.

```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!("文件名: {}\n", file_name);

    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 LLM Attention Key Length (Rust)

Source: https://docs.rs/ggus/0.5.1/ggus/trait.GGufMetaMapExt

Retrieves the length of the attention key. Returns a Result with the key length as a usize or a GGufMetaError.

```rust
fn llm_attention_key_length(&self) -> Result<usize, GGufMetaError>

获取注意力 Key 长度。

Parameters:
  None

Returns:
  Result<usize, GGufMetaError>: The attention key length or an error.
```

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

### GGufFileSimulator in Rust

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

Manages the simulation of writing a GGUF file, handling header, alignment, and metadata. It provides methods to create, configure, and transition to a tensor simulator.

```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,
        }
    }
}

```

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

### Get GGufMetaKV Key

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

Retrieves the key associated with the metadata key-value pair. The key is returned as a string slice.

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

// Gets the key of the metadata key-value pair.
```

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

### GGufReader: Create New Instance

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

Constructs a new GGufReader instance from a byte slice representing GGUF file data. This is the entry point for reading GGUF files.

```rust
impl<'a> GGufReader<'a>

/// Creates a new [`GGufReader`](struct.GGufReader.html "struct ggus::GGufReader") instance.
pub const fn new(data: &'a [u8]) -> Self
```

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

### Get GGML Tokenizer Tokens (Rust)

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

Retrieves the array of GGML tokenizer tokens (as strings) from GGuf metadata. This is useful for understanding the vocabulary of the tokenizer.

```rust
    /// 获取 ggml 分词器的词汇表。
    #[inline]
    fn tokenizer_ggml_tokens(&self) -> Result<GGufMetaValueArray<str>, GGufMetaError> {
        self.get_str_arr("tokenizer.ggml.tokens")
    }
```

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

### Get SSM State Size

Source: https://docs.rs/ggus/0.5.1/ggus/trait.GGufMetaMapExt

Retrieves the state size for State Space Models (SSM). This indicates the dimensionality of the state vector within the SSM.

```rust
fn llm_ssm_state_size(&self) -> Result<usize, GGufMetaError>
// Retrieves the state size for State Space Models (SSM).
```

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

### Populate and Access General Metadata Fields

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

Demonstrates how to populate a metadata map with various general fields, including strings, arrays, and structured data like base models. It then shows how to assert the correct retrieval of these fields using accessor methods, covering organization, licensing, URLs, DOIs, UUIDs, file types, and dataset lists.

```rust
    #[test]
    fn test_meta_map_fields() {
        // 假设 Ty, encode_string, encode_string_array, TestMetaMap, GGufFileType, GGufMetaError 是已定义的类型和函数
        // 假设 TestMetaMap 结构体有一个 data 字段，类型为 HashMap<String, (Ty, Vec<u8>)>
        // 假设存在 encode_u32 函数

        let mut map = HashMap::new();

        // 基础字段
        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(GGufFileType::AllF32 as u32)));

        // 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 1 相关字段
        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")));
        map.insert("general.base_model.0.url".to_string(), (Ty::String, encode_string("https://example.com/base1")));
        map.insert("general.base_model.0.doi".to_string(), (Ty::String, encode_string("10.1234/base1")));
        map.insert("general.base_model.0.uuid".to_string(), (Ty::String, encode_string("uuid-base-1")));
        map.insert("general.base_model.0.repo_url".to_string(), (Ty::String, encode_string("https://github.com/example/base1")));

        // Base Model 2 相关字段
        map.insert("general.base_model.1.name".to_string(), (Ty::String, encode_string("Base Model 2")));
        map.insert("general.base_model.1.author".to_string(), (Ty::String, encode_string("Base Author 2")));

        // 数组类型字段
        map.insert("general.datasets".to_string(), (Ty::Array, encode_string_array(&["dataset1", "dataset2"])))

        let meta_map = TestMetaMap { data: map };

        // 测试附加 general 字段
        assert_eq!(meta_map.general_organization().unwrap(), "TestOrg");
        assert_eq!(meta_map.general_basename().unwrap(), "base_model");
        assert_eq!(meta_map.general_quantized_by().unwrap(), "quantizer");
        assert_eq!(meta_map.general_license().unwrap(), "MIT");
        assert_eq!(meta_map.general_license_name().unwrap(), "MIT License");
        assert_eq!(meta_map.general_license_link().unwrap(), "https://mit-license.org");
        assert_eq!(meta_map.general_url().unwrap(), "https://example.com/model");
        assert_eq!(meta_map.general_doi().unwrap(), "10.1234/test");
        assert_eq!(meta_map.general_uuid().unwrap(), "123e4567-e89b-12d3-a456-426614174000");
        assert_eq!(meta_map.general_repo_url().unwrap(), "https://github.com/example/repo");
        assert_eq!(meta_map.general_filetype().unwrap(), GGufFileType::AllF32);

        // 测试 source 相关字段
        assert_eq!(meta_map.general_source_url().unwrap(), "https://example.com/source");
        assert_eq!(meta_map.general_source_doi().unwrap(), "10.1234/source");
        assert_eq!(meta_map.general_source_uuid().unwrap(), "123e4567-e89b-12d3-a456-426614174001");
        assert_eq!(meta_map.general_source_repo_url().unwrap(), "https://github.com/example/source");

        // 测试 base_model 相关字段
        assert_eq!(meta_map.general_base_model_count().unwrap(), 2);
        assert_eq!(meta_map.general_base_model_name(0).unwrap(), "Base Model 1");
        assert_eq!(meta_map.general_base_model_author(0).unwrap(), "Base Author 1");
        assert_eq!(meta_map.general_base_model_version(0).unwrap(), "1.0");
        assert_eq!(meta_map.general_base_model_organization(0).unwrap(), "Base Org 1");
        assert_eq!(meta_map.general_base_model_url(0).unwrap(), "https://example.com/base1");
        assert_eq!(meta_map.general_base_model_doi(0).unwrap(), "10.1234/base1");
        assert_eq!(meta_map.general_base_model_uuid(0).unwrap(), "uuid-base-1");
        assert_eq!(meta_map.general_base_model_repo_url(0).unwrap(), "https://github.com/example/base1");

        assert_eq!(meta_map.general_base_model_name(1).unwrap(), "Base Model 2");
        assert_eq!(meta_map.general_base_model_author(1).unwrap(), "Base Author 2");
        assert!(meta_map.general_base_model_version(1).is_err()); // 未设置的字段

        // 测试 datasets 数组字段
        let datasets: Vec<_> = meta_map.general_datasets().unwrap().collect::<Result<Vec<_>, _>>().unwrap();
        assert_eq!(datasets, vec!["dataset1", "dataset2"]);
    }
```

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

### Get Tokenizer GGML Token Types

Source: https://docs.rs/ggus/0.5.1/ggus/trait.GGufMetaMapExt

Retrieves the type for each token in the GGML tokenizer's vocabulary. This is an array of integers, likely indicating token categories.

```rust
fn tokenizer_ggml_token_type(&self) -> Result<GGufMetaValueArray<'_, i32>, GGufMetaError>
// Retrieves the token types for the GGML tokenizer.
```

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

### GGufFileWriter API Documentation

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

Provides API documentation for the GGufFileWriter, including its constructor and methods for managing GGUF file writing operations. This includes creating a writer, setting alignment, writing metadata key-value pairs, and finishing the file.

```APIDOC
GGufFileWriter Methods:

new(writer: T, header: GGufFileHeader) -> Result<Self>
  - Creates a new GGufFileWriter instance, initializing the GGUF file header.
  - Parameters:
    - writer: The underlying writer implementing std::io::Write.
    - header: The GGufFileHeader to initialize the file with.
  - Returns: A Result containing the new GGufFileWriter or an IO error.

finish() -> Result<()>
  - Finalizes the GGUF file writing process. This method should be called after all data has been written.
  - Returns: A Result indicating success or an IO error.

with_alignment(alignment: u32) -> &mut Self
  - Sets the alignment for subsequent data writes.
  - Parameters:
    - alignment: The desired alignment value.
  - Returns: A mutable reference to the GGufFileWriter.

write_alignment() -> Result<()>
  - Writes padding based on the current alignment setting.
  - Returns: A Result indicating success or an IO error.

write_meta_kv(key: &str, value: &GGUFValue) -> Result<()>
  - Writes a metadata key-value pair to the GGUF file.
  - Parameters:
    - key: The metadata key as a string slice.
    - value: The metadata value of type GGUFValue.
  - Returns: A Result indicating success or an IO error.

Related Methods:
  - write_tensor_data, write_tensor_info (not detailed in provided text but implied for full functionality)
```

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

### Get SSM Inner Size

Source: https://docs.rs/ggus/0.5.1/ggus/trait.GGufMetaMapExt

Retrieves the inner size parameter for State Space Models (SSM). This value is part of the internal configuration of SSM layers.

```rust
fn llm_ssm_inner_size(&self) -> Result<usize, GGufMetaError>
// Retrieves the inner size for State Space Models (SSM).
```

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

### GGufFileHeader Methods

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

Lists the available methods for the GGufFileHeader struct, such as checking magic number correctness, endianness, retrieving the magic number, and creating new instances.

```APIDOC
Struct: GGufFileHeader

Methods:
  - is_magic_correct()
    Description: Checks if the magic number is correct.
  - is_native_endian()
    Description: Checks if the file uses native endianness.
  - magic()
    Description: Returns the magic number of the GGUF file.
  - new()
    Description: Creates a new GGufFileHeader instance.
```

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

### Get Tokenizer GGML Model Name

Source: https://docs.rs/ggus/0.5.1/ggus/trait.GGufMetaMapExt

Retrieves the name of the tokenizer model used for GGML. This identifies the specific tokenizer configuration associated with the GGML format.

```rust
fn tokenizer_ggml_model(&self) -> Result<&str, GGufMetaError>
// Retrieves the tokenizer model for GGML.
```

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

### Create GGufMetaKV Instance

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

Constructs a new GGufMetaKV instance from a slice of byte slices. This method is used to initialize the metadata key-value pair structure.

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

// Creates a new `GGufMetaKV` instance.
```

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

### Populate General Metadata Fields in Rust

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

This Rust code snippet demonstrates how to construct and populate a metadata map with various general fields. It includes basic model information, additional attributes like license and file type, source details, and configurations for base models, simulating a comprehensive metadata structure for testing.

```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")),
    );
    map.insert(
        "general.base_model.0.url".to_string(),
```

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

### Get LLM Attention Layer Norm Epsilon (Rust)

Source: https://docs.rs/ggus/0.5.1/ggus/trait.GGufMetaMapExt

Retrieves the epsilon parameter for layer normalization. Returns a Result with the f32 epsilon value or a GGufMetaError.

```rust
fn llm_attention_layer_norm_epsilon(&self) -> Result<f32, GGufMetaError>

获取归一化 ε 参数。

Parameters:
  None

Returns:
  Result<f32, GGufMetaError>: The layer norm epsilon or an error.
```

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

### Rust: TryFrom and TryInto Implementations

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

Documentation for the standard Rust traits TryFrom and TryInto, which provide fallible type conversions. This section details their associated error types and the core conversion methods.

```APIDOC
impl<T, U> TryFrom<U> for T
  where U: Into<T>

  Provides a way to convert a value of type U into a value of type T, which may fail.
  Associated Types:
    - Error: The type returned in the event of a conversion error (Infallible in this case).
  Methods:
    - try_from(value: U) -> Result<T, Self::Error>
      Performs the conversion.

impl<T, U> TryInto<U> for T
  where U: TryFrom<T>

  Provides a way to convert a value of type T into a value of type U, which may fail.
  Associated Types:
    - Error: The type returned in the event of a conversion error (same as U's TryFrom::Error).
  Methods:
    - try_into() -> Result<U, Self::Error>
      Performs the conversion.
```

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

### Get LLM Attention Clamp K/Q/V Threshold (Rust)

Source: https://docs.rs/ggus/0.5.1/ggus/trait.GGufMetaMapExt

Retrieves the clamping threshold for K/Q/V values in attention. Returns a Result with the f32 threshold or a GGufMetaError.

```rust
fn llm_attention_clamp_kqv(&self) -> Result<f32, GGufMetaError>

获取 K/Q/V 限幅阈值。

Parameters:
  None

Returns:
  Result<f32, GGufMetaError>: The clamping threshold or an error.
```

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

### GGufReader API Documentation

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

Comprehensive API documentation for the GGufReader struct, including its methods for reading GGUF file components like headers, strings, and tensors. It details parameters, return types, and error handling.

```APIDOC
GGufReader Methods:

  GGufReader::new()
    - Constructor for GGufReader.
    - No parameters.
    - Returns: An instance of GGufReader.

  GGufReader::read_header(&mut self) -> Result<GGufFileHeader, GGufReadError>
    - Reads the GGUF file header from the current reader position.
    - Parameters:
      - self: A mutable reference to the GGufReader instance.
    - Returns:
      - Ok(GGufFileHeader): If the header is read successfully.
      - Err(GGufReadError): If an error occurs during header reading.

  GGufReader::read(&mut self) -> Result<..., GGufReadError>
    - Reads the entire GGUF file content.
    - Parameters:
      - self: A mutable reference to the GGufReader instance.
    - Returns:
      - Result: The parsed GGUF file content or an error.

  GGufReader::read_arr_header(&mut self) -> Result<..., GGufReadError>
    - Reads an array header from the GGUF file.
    - Parameters:
      - self: A mutable reference to the GGufReader instance.
    - Returns:
      - Result: The array header information or an error.

  GGufReader::read_bool(&mut self) -> Result<bool, GGufReadError>
    - Reads a boolean value from the GGUF file.
    - Parameters:
      - self: A mutable reference to the GGufReader instance.
    - Returns:
      - Ok(bool): The boolean value read.
      - Err(GGufReadError): If an error occurs.

  GGufReader::read_meta_kv(&mut self) -> Result<..., GGufReadError>
    - Reads a key-value pair from the GGUF metadata.
    - Parameters:
      - self: A mutable reference to the GGufReader instance.
    - Returns:
      - Result: The metadata key-value pair or an error.

  GGufReader::read_str(&mut self) -> Result<String, GGufReadError>
    - Reads a null-terminated string from the GGUF file.
    - Parameters:
      - self: A mutable reference to the GGufReader instance.
    - Returns:
      - Ok(String): The string read.
      - Err(GGufReadError): If an error occurs.

  GGufReader::read_str_unchecked(&mut self) -> Result<String, GGufReadError>
    - Reads a string without bounds checking.
    - Parameters:
      - self: A mutable reference to the GGufReader instance.
    - Returns:
      - Result: The string read or an error.

  GGufReader::read_tensor_meta(&mut self) -> Result<..., GGufReadError>
    - Reads tensor metadata from the GGUF file.
    - Parameters:
      - self: A mutable reference to the GGufReader instance.
    - Returns:
      - Result: The tensor metadata or an error.

  GGufReader::remaining(&self) -> usize
    - Returns the number of bytes remaining to be read in the GGUF file.
    - Parameters:
      - self: An immutable reference to the GGufReader instance.
    - Returns:
      - usize: The number of remaining bytes.

GGufReader Trait Implementations:

  impl Clone for GGufReader<'a>
    - Provides cloning functionality for GGufReader instances.

GGufReader Auto Trait Implementations:

  impl Freeze for GGufReader<'a>
  impl RefUnwindSafe for GGufReader<'a>
  impl Send for GGufReader<'a>
  impl Sync for GGufReader<'a>
  impl Unpin for GGufReader<'a>
  impl UnwindSafe for GGufReader<'a>
    - These indicate thread safety and memory management characteristics.

GGufReader Blanket Implementations:

  impl Any for T
  impl Borrow<T> for T
  impl BorrowMut<T> for T
  impl CloneToUninit for T
  impl From<T> for T
  impl Into<U> for T
  impl IntoEither for T
  impl Pointable for T
  impl ToOwned for T
  impl TryFrom<U> for T
  impl TryInto<U> for T
    - These are standard Rust trait implementations providing common functionalities.
```

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

### Get GGufMetaKV Value Reader

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

Returns a GGufReader instance for the metadata value. This allows for structured reading of the value based on its type.

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

// Gets the value reader for the metadata key-value pair.
```

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

### Rust Trait Methods: Any, Borrow, BorrowMut, From, Into (APIDOC)

Source: https://docs.rs/ggus/0.5.1/ggus/struct.GGufExtNotMatch

Comprehensive documentation for key methods associated with generic Rust trait implementations. Covers type identification, immutable/mutable borrowing, and type conversions.

```APIDOC
trait Any:
  fn type_id(&self) -> TypeId
    - Gets the TypeId of `self`.

trait Borrow<T>:
  fn borrow(&self) -> &T
    - Immutably borrows from an owned value.

trait BorrowMut<T>:
  fn borrow_mut(&mut self) -> &mut T
    - Mutably borrows from an owned value.

trait From<T>:
  fn from(t: T) -> Self
    - Returns the argument unchanged.

trait Into<U>:
  fn into(self) -> U
    - Calls `U::from(self)`.
    - This conversion is whatever the implementation of `From<T> for U` chooses to do.
```

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

### Rust: Get TypeId from Any trait

Source: https://docs.rs/ggus/0.5.1/ggus/enum.GGmlType

Retrieves the unique TypeId for a given type. This method is part of the Any trait and is fundamental for dynamic type introspection in Rust.

```APIDOC
Any::type_id

fn type_id(&self) -> TypeId

Description: Gets the TypeId of `self`.
Parameters:
  - self: A reference to the object implementing the Any trait.
Returns:
  - TypeId: The unique identifier for the type of `self`.
```

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

### Rust Iterator enumerate Method

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

Creates an iterator which yields pairs of the current iteration count and the element. The count starts at zero.

```rust
fn enumerate(self) -> Enumerate<Self> where Self: Sized
```

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

### Rust Conversion Traits: TryFrom and TryInto

Source: https://docs.rs/ggus/0.5.1/ggus/enum.GGufReadError

Documentation for the core Rust traits TryFrom and TryInto, which enable fallible type conversions. Includes details on their associated Error types and the primary conversion methods.

```APIDOC
trait TryFrom<U>: Sized {
    type Error: Debug;

    fn try_from(value: U) -> Result<Self, Self::Error>;
}

// Description: The type returned in the event of a conversion error.
// Source: https://doc.rust-lang.org/nightly/core/convert/mod.rs.html#816

// Description: Performs the conversion.
// Parameters:
//   value: The input value of type U to convert.
// Returns: A Result containing the converted value of type T or an error.
// Source: https://doc.rust-lang.org/nightly/core/convert/mod.rs.html#797-799
```

```APIDOC
trait TryInto<U>: Sized {
    type Error: Debug;

    fn try_into(self) -> Result<U, Self::Error>;
}

// Description: The type returned in the event of a conversion error.
// Source: https://doc.rust-lang.org/nightly/core/convert/mod.rs.html#801

// Description: Performs the conversion.
// Parameters:
//   self: The value to convert.
// Returns: A Result containing the converted value of type U or an error.
// Source: https://doc.rust-lang.org/nightly/core/convert/mod.rs.html#804
```

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

### GGufTensorMeta Methods

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

Provides methods for creating and accessing information from GGufTensorMeta. Includes safe and unsafe constructors, and a method to retrieve the tensor's name.

```APIDOC
impl<'a> GGufTensorMeta<'a>

  pub const unsafe fn new_unchecked(data: &'a [u8]) -> Self
    - Creates a new GGufTensorMeta instance without checking data validity.
    - Safety: The caller must ensure the provided data is in a valid GGUF tensor metadata format to avoid undefined behavior.

  pub fn new(data: &'a [u8]) -> Result<Self, GGufReadError>
    - Creates a new GGufTensorMeta instance with data validation.
    - Returns: A Result containing the GGufTensorMeta instance on success or a GGufReadError on failure.

  pub fn name(&self) -> &'a str
    - Retrieves the name of the tensor metadata.
    - Returns: A string slice representing the tensor name.
```

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

### Get Chat Template (Rust)

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

Retrieves the chat template string from GGuf metadata. This template defines how to format conversational inputs for models that support chat-based interaction.

```rust
    /// 获取聊天模板。
    #[inline]
    fn tokenizer_chat_template(&self) -> Result<&str, GGufMetaError> {
        self.get_str("tokenizer.chat_template")
    }
```