Huggingface.js documentation
@huggingface/gguf
@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
npm install @huggingface/gguf
Cách sử dụng
Cách sử dụng cơ bản
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ộ
// 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ó:
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: ["<unk>", "<s>", "</s>", ...], 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, whisper.cpp và ggml.
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, lora weights, 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 }>:
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. Bạn có thể dump metadata GGUF và danh sách các tensor bằng lệnh này:
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.ggufVí 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:
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 của @platypii (giấy phép MIT)
- https://github.com/ahoylabs/gguf.js của @biw @dkogut1996 @spencekim (giấy phép MIT)
🔥❤️
Update on GitHub