{"id":51090581,"url":"https://github.com/magomedcoder/gguf.go","last_synced_at":"2026-06-24T01:33:00.052Z","repository":{"id":365564649,"uuid":"1262281371","full_name":"magomedcoder/gguf.go","owner":"magomedcoder","description":"Запуск ML-моделей в формате GGUF на чистом Go","archived":false,"fork":false,"pushed_at":"2026-06-17T21:42:57.000Z","size":126,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-17T23:21:44.334Z","etag":null,"topics":["gguf","gguf-model","gguf-model-support","gguf-models","go","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/magomedcoder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-07T19:58:57.000Z","updated_at":"2026-06-17T21:43:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/magomedcoder/gguf.go","commit_stats":null,"previous_names":["magomedcoder/gguf.go"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/magomedcoder/gguf.go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magomedcoder%2Fgguf.go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magomedcoder%2Fgguf.go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magomedcoder%2Fgguf.go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magomedcoder%2Fgguf.go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/magomedcoder","download_url":"https://codeload.github.com/magomedcoder/gguf.go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magomedcoder%2Fgguf.go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34713789,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gguf","gguf-model","gguf-model-support","gguf-models","go","golang"],"created_at":"2026-06-24T01:32:59.759Z","updated_at":"2026-06-24T01:33:00.017Z","avatar_url":"https://github.com/magomedcoder.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gguf.go - запуск ML-моделей в формате **GGUF** на чистом **Go**.\n\n\u003e **Ранний этап разработки.**\n\n**gguf.go** - лёгковесный способ запуска GGUF-моделей на языке Go без llama.cpp.\n\nФормат **GGUF** используется в экосистеме llama.cpp.\n\n[GGUF-FORMAT.md](GGUF-FORMAT.md) - описание формата GGUF\n\nПроект можно использовать как **библиотеку** (inference из Go-кода) и как **HTTP-сервер** (`gguf serve` или пакет `server`).\n\n**Внешних Go-зависимостей нет** - только стандартная библиотека.\n\nОпционально: **CUDA** через Driver API (`libcuda.so`, сборка `-tags cuda`, CGO).\n\n## Что уже работает\n\n- парсинг GGUF v2/v3 (`info`, `inspect`), memory-map (`LoadMapped`, zero-copy `RawView`);\n- деквантизация и matmul: Q8_0, Q4_0, Q4_K;\n- базовые ops: RoPE, RMSNorm, GQA attention, SwiGLU;\n- forward pass **Qwen3** + KV-cache;\n- tokenizer BPE из метаданных GGUF;\n- chat template ChatML/Qwen (`--chat`, `--thinking`, `FormatChatUser`);\n- генерация текста: `gguf run` (prefill + greedy / temperature / top-k / top-p);\n- HTTP-сервер: `gguf serve` (`/generate`, `/models`, JSON + SSE streaming);\n- **CUDA offload** (`-ngl N`): matmul первых N transformer-слоёв на GPU (сборка `-tags cuda`).\n\n---\n\nНа текущем этапе для разработки и тестирования используется Qwen3-0.6B-Q8_0.gguf\n\n```bash\nmkdir -p models\n\ncurl -L -o models/Qwen3-0.6B-Q8_0.gguf https://huggingface.co/Qwen/Qwen3-0.6B-GGUF/resolve/main/Qwen3-0.6B-Q8_0.gguf\n```\n\n---\n\n## Сборка\n\n### Локально (Go 1.26)\n\n```bash\ngo build -o build/gguf ./cmd/gguf\n```\n\nБез CGO - кросс-компиляция на любую платформу\n\n### CUDA (NVIDIA GPU, опционально)\n\nТребуется драйвер NVIDIA (`libcuda.so`) и CGO.\n\nCUDA Toolkit не нужен - используется Driver API через `dlopen`.\n\n```bash\nCGO_ENABLED=1 go build -tags cuda -o build/gguf ./cmd/gguf\n```\n\nПроверка GPU matmul:\n\n```bash\nCGO_ENABLED=1 go test -tags=cuda ./pkg/gpu/cuda/...\n```\n\n`-ngl N` - matmul первых N transformer-слоёв на GPU (макс. `block_count` из `gguf inspect`; Qwen3-0.6B - 28).\n\nСейчас на GPU только matmul: Q8_0 без деквантизации в FP32, остальные типы - через FP32. Attention, norm и RoPE - на CPU. Q8_0 kernel требует GPU sm_70+.\n\nБез `-tags cuda` при `-ngl \u003e 0` будет ошибка `gpu: CUDA недоступна`.\n\n### Через Docker\n\nMulti-stage `Dockerfile`: CPU-кросс-компиляция по умолчанию, отдельные target'ы для CUDA.\n\n**CPU (по умолчанию)** - все платформы, `CGO_ENABLED=0`:\n\n```bash\ndocker build -t gguf-build .\ndocker run --rm -v \"$(pwd)/build:/out\" gguf-build\n```\n\n**CUDA** - только `linux-amd64/gguf-cuda`:\n\n```bash\ndocker build --target cuda -t gguf-cuda .\ndocker run --rm -v \"$(pwd)/build:/out\" gguf-cuda\n```\n\n**CPU + CUDA**:\n\n```bash\ndocker build --target release -t gguf-release .\ndocker run --rm -v \"$(pwd)/build:/out\" gguf-release\n```\n\n| Target / режим | Результат                     |\n|----------------|-------------------------------|\n| *(default)*    | CPU-бинарники всех платформ   |\n| `cuda`         | `build/linux-amd64/gguf-cuda` |\n| `release`      | CPU + `gguf-cuda`             |\n\n| Платформа     | CPU-бинарник                   | CUDA-бинарник (target `cuda` / `release`) |\n|---------------|--------------------------------|-------------------------------------------|\n| Linux amd64   | `build/linux-amd64/gguf`       | `build/linux-amd64/gguf-cuda`             |\n| Linux arm64   | `build/linux-arm64/gguf`       | -                                         |\n| Windows amd64 | `build/windows-amd64/gguf.exe` | -                                         |\n| Windows arm64 | `build/windows-arm64/gguf.exe` | -                                         |\n| macOS amd64   | `build/darwin-amd64/gguf`      | -                                         |\n| macOS arm64   | `build/darwin-arm64/gguf`      | -                                         |\n\n\n\u003e **Примечание.** Путь к бинарнику зависит от способа сборки:\n\u003e - локально CPU: `./build/gguf`\n\u003e - локально CUDA: `./build/gguf` (с `-tags cuda`)\n\u003e - Docker CPU: `./build/\u003cos\u003e-\u003carch\u003e/gguf` (на Windows: `gguf.exe`)\n\u003e - Docker CUDA: `./build/linux-amd64/gguf-cuda`\n\n---\n\n## CLI\n\n### `gguf info`\n\nКраткая сводка о модели: версия GGUF, архитектура, имя, число тензоров, размер весов, длина контекста.\n\n```bash\n./build/gguf info -m ./models/Qwen3-0.6B-Q8_0.gguf\n```\n\n| Флаг | Описание             |\n|------|----------------------|\n| `-m` | путь к файлу `.gguf` |\n\n### `gguf inspect`\n\nПолный дамп метаданных и списка тензоров (имя, тип, размерности, размер в байтах).\n\n```bash\n./build/gguf inspect ./models/Qwen3-0.6B-Q8_0.gguf\n```\n\nАргумент - путь к файлу, без флагов.\n\n### `gguf run`\n\nГенерация текста: prefill промпта -\u003e autoregressive decode -\u003e вывод в stdout.\n\n```bash\n./build/gguf run -m ./models/Qwen3-0.6B-Q8_0.gguf --chat -p \"Привет\" -n 64\n```\n\n| Флаг         | По умолчанию | Описание                                        |\n|--------------|--------------|-------------------------------------------------|\n| `-m`         | -            | путь к файлу `.gguf`                            |\n| `-p`         | -            | текст промпта                                   |\n| `-n`         | `128`        | максимум новых токенов                          |\n| `--temp`     | `0`          | температура sampling (`0` = greedy)             |\n| `--top-k`    | `0`          | top-k (`0` = выключено)                         |\n| `--top-p`    | `1`          | nucleus sampling (`1` = выключено)              |\n| `--seed`     | `0`          | seed PRNG                                       |\n| `--chat`     | `false`      | обернуть промпт в ChatML/Qwen template          |\n| `--thinking` | `false`      | режим размышления Qwen3 (с `--chat`)            |\n| `-ngl`       | `0`          | matmul N transformer-слоёв на GPU (CUDA-сборка) |\n\nДля **Qwen3 Instruct** используйте `--chat`, иначе модель ответит некорректно.\n\nПример с sampling:\n\n```bash\n./build/gguf run -m ./models/Qwen3-0.6B-Q8_0.gguf --chat -p \"Привет\" -n 64 --temp 0.7 --top-k 40 --top-p 0.9 --seed 42\n```\n\nС размышлением:\n\n```bash\n./build/gguf run -m ./models/Qwen3-0.6B-Q8_0.gguf --chat --thinking -p \"Привет\" -n 64\n```\n\nС GPU offload (28 слоёв, CUDA-сборка):\n\n```bash\n./build/gguf run -m ./models/Qwen3-0.6B-Q8_0.gguf --chat -p \"Привет\" -ngl 28\n```\n\n### `gguf serve`\n\nHTTP-сервер для генерации текста по API.\n\nGraceful shutdown по `Ctrl+C` (SIGINT/SIGTERM).\n\n```bash\n./build/gguf serve -m ./models/Qwen3-0.6B-Q8_0.gguf --addr 127.0.0.1:8000\n```\n\n| Флаг     | По умолчанию     | Описание                                        |\n|----------|------------------|-------------------------------------------------|\n| `-m`     | -                | путь к файлу `.gguf`                            |\n| `--addr` | `127.0.0.1:8000` | адрес HTTP-сервера                              |\n| `-ngl`   | `0`              | matmul N transformer-слоёв на GPU (CUDA-сборка) |\n\n#### API\n\n| Метод | Путь                   | Описание                        |\n|-------|------------------------|---------------------------------|\n| GET   | `/models`              | метаданные загруженной модели   |\n| POST  | `/generate`            | генерация текста (JSON или SSE) |\n| POST  | `/completion`          | алиас `/generate`               |\n| POST  | `/v1/chat/completions` | chat API (messages + stream)    |\n\nТело `POST /generate` (`Content-Type: application/json`):\n\n| Поле          | Тип    | По умолчанию | Описание                    |\n|---------------|--------|--------------|-----------------------------|\n| `prompt`      | string | -            | текст запроса (обязательно) |\n| `max_tokens`  | int    | `128`        | максимум новых токенов      |\n| `temperature` | float  | `0`          | `0` = greedy                |\n| `top_k`       | int    | `0`          | top-k sampling              |\n| `top_p`       | float  | `1`          | nucleus sampling            |\n| `seed`        | uint   | `0`          | seed PRNG                   |\n| `chat`        | bool   | `false`      | ChatML/Qwen template        |\n| `stream`      | bool   | `false`      | SSE streaming               |\n| `system`      | string | -            | system prompt (с `chat`)    |\n| `thinking`    | bool   | `false`      | режим размышления Qwen3     |\n\nОтвет без stream:\n\n```json\n{\n  \"text\": \"...\",\n  \"tokens\": 32\n}\n```\n\nStreaming (SSE) - события `data: {\"token\":\"...\"}` и в конце `data: {\"done\":true}`.\n\nПримеры:\n\n```bash\ncurl -s localhost:8000/generate -H 'Content-Type: application/json' -d '{\"prompt\":\"Привет\",\"chat\":true, \"max_tokens\":32}'\n\ncurl -N localhost:8000/generate -H 'Content-Type: application/json' -d '{\"prompt\":\"Привет\",\"chat\":true,\"stream\":true,\"max_tokens\":32}'\n\ncurl -s localhost:8000/models\n\ncurl -s localhost:8000/v1/chat/completions -H 'Content-Type: application/json' -d '{\"messages\":[{\"role\":\"user\",\"content\":\"Привет\"}],\"max_tokens\":32}'\n```\n\nПример ответа `/v1/chat/completions`:\n\n```json\n{\n  \"object\": \"chat.completion\",\n  \"choices\": [\n    {\n      \"message\": {\n        \"role\": \"assistant\",\n        \"content\": \"...\"\n      }\n    }\n  ],\n  \"usage\": {\n    \"prompt_tokens\": 10,\n    \"completion_tokens\": 5,\n    \"total_tokens\": 15\n  }\n}\n```\n\n---\n\n## Утилиты для отладки\n\n### `debugtok`\n\nПроверяет encode промпта и logits после prefill: top-5 токенов и greedy-следующий.\n\n```bash\ngo run ./cmd/debugtok ./models/Qwen3-0.6B-Q8_0.gguf \"Hello\"\n```\n\n### `vocab`\n\nПоказывает конфиг Qwen3 (`head_dim`, число heads) и ID special tokens в словаре.\n\n```bash\ngo run ./cmd/vocab ./models/Qwen3-0.6B-Q8_0.gguf\n```\n\n---\n\n## Использование как библиотеки\n\n### Inference\n\n```go\nimport \"github.com/magomedcoder/gguf.go\"\n\nengine, err := gguf.Load(\"./models/Qwen3-0.6B-Q8_0.gguf\", gguf.LoadOptions{\n  NGL: 0, // matmul N слоёв на GPU; \u003c= block_count, нужна CUDA-сборка\n})\nctx, err := engine.NewContext()\n\nprompt, err := gguf.FormatChatUser(\"Привет\", gguf.ChatOptions{\n  Metadata: engine.Metadata(),\n})\ntext, err := ctx.Generate(prompt, gguf.GenerateParams{\n  MaxTokens: 128,\n  Sampler:   gguf.Greedy,\n})\n```\n\n### Пошаговый decode\n\n```go\nsess, err := ctx.StartGeneration(prompt)\nfor i := 0; i \u003c maxTokens; i++ {\n  id, err := sess.DecodeStep(gguf.Greedy)\n  if id \u003c 0 {\n    break\n  }\n\n  fmt.Print(sess.DecodeToken(id))\n}\n```\n\n### Sampling с temperature / top-k / top-p\n\n```go\nsampler := gguf.NewSampler(gguf.SamplerConfig{\n  Temp: 0.7,\n  TopK: 40,\n  TopP: 0.9,\n  Seed: 42,\n})\ntext, err := ctx.Generate(prompt, gguf.GenerateParams{\n  MaxTokens: 64,\n  Sampler:   sampler,\n})\n```\n\n### Загрузка через mmap (zero-copy веса)\n\n```go\nengine, err := gguf.LoadMapped(\"./models/Qwen3-0.6B-Q8_0.gguf\", gguf.LoadOptions{NGL: 0})\n```\n\n### GPU offload из кода\n\n```go\nengine, err := gguf.Load(\"./models/Qwen3-0.6B-Q8_0.gguf\", gguf.LoadOptions{\n  NGL: 28, // нужна сборка -tags cuda\n})\n```\n\n### Парсинг GGUF без inference\n\n```go\nimport \"github.com/magomedcoder/gguf.go\"\n\nr, err := gguf.OpenFile(\"./models/Qwen3-0.6B-Q8_0.gguf\")\n\narch, _ := r.Metadata.String(\"general.architecture\")\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagomedcoder%2Fgguf.go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagomedcoder%2Fgguf.go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagomedcoder%2Fgguf.go/lists"}