# `@huggingface/gguf` Trình phân tích GGUF hoạt động trên các tệp được lưu trữ từ xa. ## Thông số kỹ thuật Spec: https://github.com/ggerganov/ggml/blob/master/docs/gguf.md Cài đặt tham chiếu (Python): https://github.com/ggerganov/llama.cpp/blob/master/gguf-py/gguf/gguf_reader.py ## Cài đặt ```bash npm install @huggingface/gguf ``` ## Cách sử dụng ### Cách sử dụng cơ bản ```ts import { GGMLQuantizationType, gguf } from "@huggingface/gguf"; // remote GGUF file from https://huggingface.co/TheBloke/Llama-2-7B-Chat-GGUF const URL_LLAMA = "https://huggingface.co/TheBloke/Llama-2-7B-Chat-GGUF/resolve/191239b/llama-2-7b-chat.Q2_K.gguf"; const { metadata, tensorInfos } = await gguf(URL_LLAMA); console.log(metadata); // { // version: 2, // tensor_count: 291n, // kv_count: 19n, // "general.architecture": "llama", // "general.file_type": 10, // "general.name": "LLaMA v2", // ... // } console.log(tensorInfos); // [ // { // name: "token_embd.weight", // shape: [4096n, 32000n], // dtype: GGMLQuantizationType.Q2_K, // }, // ... , // { // name: "output_norm.weight", // shape: [4096n], // dtype: GGMLQuantizationType.F32, // } // ] ``` ### Đọc tệp cục bộ ```ts // Reading a local file. (Not supported on browser) const { metadata, tensorInfos } = await gguf( './my_model.gguf', { allowLocalFile: true }, ); ``` ### Metadata có kiểu Bạn có thể lấy metadata kèm thông tin kiểu bằng cách đặt `typedMetadata: true`. Điều này cung cấp cả giá trị gốc và kiểu dữ liệu GGUF của nó: ```ts import { GGMLQuantizationType, GGUFValueType, gguf } from "@huggingface/gguf"; const URL_LLAMA = "https://huggingface.co/TheBloke/Llama-2-7B-Chat-GGUF/resolve/191239b/llama-2-7b-chat.Q2_K.gguf"; const { metadata, typedMetadata } = await gguf(URL_LLAMA, { typedMetadata: true }); console.log(typedMetadata); // { // version: { value: 2, type: GGUFValueType.UINT32 }, // tensor_count: { value: 291n, type: GGUFValueType.UINT64 }, // kv_count: { value: 19n, type: GGUFValueType.UINT64 }, // "general.architecture": { value: "llama", type: GGUFValueType.STRING }, // "general.file_type": { value: 10, type: GGUFValueType.UINT32 }, // "general.name": { value: "LLaMA v2", type: GGUFValueType.STRING }, // "llama.attention.head_count": { value: 32, type: GGUFValueType.UINT32 }, // "llama.attention.layer_norm_rms_epsilon": { value: 9.999999974752427e-7, type: GGUFValueType.FLOAT32 }, // "tokenizer.ggml.tokens": { value: ["", "", "", ...], type: GGUFValueType.ARRAY, subType: GGUFValueType.STRING }, // "tokenizer.ggml.scores": { value: [0.0, -1000.0, -1000.0, ...], type: GGUFValueType.ARRAY, subType: GGUFValueType.FLOAT32 }, // ... // } // Access both value and type information console.log(typedMetadata["general.architecture"].value); // "llama" console.log(typedMetadata["general.architecture"].type); // GGUFValueType.STRING (8) // For arrays, subType indicates the type of array elements console.log(typedMetadata["tokenizer.ggml.tokens"].type); // GGUFValueType.ARRAY (9) console.log(typedMetadata["tokenizer.ggml.tokens"].subType); // GGUFValueType.STRING (8) ``` ### Được định kiểu nghiêm ngặt Mặc định, các trường đã biết trong `metadata` được gán kiểu dữ liệu. Điều này bao gồm các trường khác nhau được tìm thấy trong [llama.cpp](https://github.com/ggerganov/llama.cpp), [whisper.cpp](https://github.com/ggerganov/whisper.cpp) và [ggml](https://github.com/ggerganov/ggml). ```ts const { metadata, tensorInfos } = await gguf(URL_MODEL); // Type check for model architecture at runtime if (metadata["general.architecture"] === "llama") { // "llama.attention.head_count" is a valid key for llama architecture, this is typed as a number console.log(model["llama.attention.head_count"]); // "mamba.ssm.conv_kernel" is an invalid key, because it requires model architecture to be mamba console.log(model["mamba.ssm.conv_kernel"]); // error } ``` ### Tắt kiểu dữ liệu nghiêm ngặt Vì định dạng GGUF có thể được dùng để lưu trữ các tensor, về mặt kỹ thuật chúng ta có thể sử dụng nó cho các mục đích khác. Ví dụ, lưu trữ [control vectors](https://github.com/ggerganov/llama.cpp/pull/5970), [lora weights](https://github.com/ggerganov/llama.cpp/pull/2632), v.v. Nếu bạn muốn sử dụng cấu trúc metadata GGUF của riêng mình, bạn có thể tắt kiểu dữ liệu nghiêm ngặt bằng cách ép kiểu kết quả phân tích thành `GGUFParseOutput<{ strict: false }>`: ```ts const { metadata, tensorInfos }: GGUFParseOutput<{ strict: false }> = await gguf(URL_LLAMA); ``` ## Giao diện dòng lệnh Gói này cung cấp một CLI tương đương với script [`gguf_dump.py`](https://github.com/ggml-org/llama.cpp/blob/7a2c913e66353362d7f28d612fd3c9d51a831eda/gguf-py/gguf/scripts/gguf_dump.py). Bạn có thể dump metadata GGUF và danh sách các tensor bằng lệnh này: ```bash npx @huggingface/gguf my_model.gguf # or, with a remote GGUF file: # npx @huggingface/gguf https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q4_K_M.gguf ``` Ví dụ về đầu ra: ``` * Dumping 36 key/value pair(s) Idx | Count | Value ----|--------|---------------------------------------------------------------------------------- 1 | 1 | version = 3 2 | 1 | tensor_count = 292 3 | 1 | kv_count = 33 4 | 1 | general.architecture = "llama" 5 | 1 | general.type = "model" 6 | 1 | general.name = "Meta Llama 3.1 8B Instruct" 7 | 1 | general.finetune = "Instruct" 8 | 1 | general.basename = "Meta-Llama-3.1" [truncated] * Dumping 292 tensor(s) Idx | Num Elements | Shape | Data Type | Name ----|--------------|--------------------------------|-----------|-------------------------- 1 | 64 | 64, 1, 1, 1 | F32 | rope_freqs.weight 2 | 525336576 | 4096, 128256, 1, 1 | Q4_K | token_embd.weight 3 | 4096 | 4096, 1, 1, 1 | F32 | blk.0.attn_norm.weight 4 | 58720256 | 14336, 4096, 1, 1 | Q6_K | blk.0.ffn_down.weight [truncated] ``` Ngoài ra, bạn có thể cài đặt gói này ở chế độ toàn cục, điều này sẽ cung cấp lệnh `gguf-view`: ```bash npm i -g @huggingface/gguf gguf-view my_model.gguf ``` ## Hugging Face Hub Hub hỗ trợ tất cả các định dạng tệp và có các tính năng tích hợp sẵn cho định dạng GGUF. Tìm thêm thông tin tại: http://hf.co/docs/hub/gguf. ## Lời cảm ơn & Nguồn cảm hứng - https://github.com/hyparam/hyllama bởi @platypii (giấy phép MIT) - https://github.com/ahoylabs/gguf.js bởi @biw @dkogut1996 @spencekim (giấy phép MIT) 🔥❤️