Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

Gemma 4 Text-Only Support

Đang mở
  • Có gì không ổn?
#33 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
15/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Đình trệ
Công nghệ
kotlin
Lĩnh vực
backend, machine-learning

Hướng nghiên cứu

Start by inspecting the existing Gemma3n ingestion and runtime paths, then read the Gemma 4 config, tokenizer, and generation metadata requirements in this issue. The work spans model loading, attention, KV-cache, CLI integration, and CI; completion means the listed unit, integration, and smoke tests pass for Gemma 4 E2B, with Gemma3n unaffected.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

Summary

Implement complete text-only inference for Gemma 4 models (E2B, E4B, optionally 31B) in SKaiNET-transformers. This covers config parsing, weight loading, tokenizer with special tokens, prompt formatting with Gemma 4 control tokens, hybrid attention with p-RoPE, KV-cache sharing, and kgemma CLI integration.

Motivation

Gemma 4 text-only is the foundation for all further Gemma 4 work. Correct config parsing, weight loading, and attention semantics must be in place before multimodal or MoE extensions.

Functional Requirements

1. Config Parser & Model Metadata
  • New Gemma4ConfigParser recognizing model_type=gemma4 and architectures=["Gemma4ForConditionalGeneration"]
  • Parse text_config fields: layer_types, max_position_embeddings, sliding_window, num_kv_shared_layers, rope_parameters (full vs sliding, rope_type="proportional", partial_rotary_factor), global_head_dim
  • New Gemma4ModelMetadata class with all parsed fields
  • Validate bos_token_id, eos_token_id, pad_token_id consistency with generation_config.json
2. Weight Loading (SafeTensors & GGUF)
  • Gemma4SafeTensorsWeightLoader with Gemma-4-specific HF tensor name -> runtime name mapping
  • Support single-file and sharded-index (model.safetensors.index.json)
  • DType handling (BF16/F16/F32) and necessary transposes
  • PLE (Per-Layer Embeddings) table loading
  • GGUF streaming load path with QuantPolicy handling (DEQUANTIZE_TO_FP32, allowQuantized=true)
3. Tokenizer & Special Tokens
  • Load tokenizer.json + tokenizer_config.json correctly
  • Support add_bos_token=true, padding_side=left
  • Register all Gemma 4 special tokens: <|turn>, <turn|>, <|think|>, <|tool>, <tool|>, <|tool_call>, <tool_call|>, <|tool_response>, <tool_response|>, <|image|>, <|audio|>
  • Ensure token ID consistency (E2B: bos=2, eos=1, pad=0)
  • Backward compatibility with existing GGUFTokenizer.fromTokenizerJson(...) path
4. Prompt Formatter
  • Gemma4PromptFormatter implementing the official turn schema: 
    <|turn>system
{system_message}<turn|>
<|turn>user
{user_message}<turn|>
<|turn>model
  • Thinking mode: <|think|> injection in system prompt
  • Tool-calling: <|tool>...<tool|>, <|tool_call>...<tool_call|>, <|tool_response>...<tool_response|> sequences
  • <|tool_response> as stop sequence during inference
  • Output escaping via <|"|> delimiter for tool arguments
5. Runtime: Hybrid Attention, KV-Cache, Long-Context
  • Configuration-driven hybrid attention from layer_types (sliding_attention / full_attention interleaving; last layer always global)
  • Proportional RoPE (p-RoPE) for global attention layers with separate rope_theta for sliding vs full
  • global_head_dim support for global attention layers
  • KV-sharing: num_kv_shared_layers — last N layers share KV cache
  • Respect max_position_embeddings (128K for E2B/E4B, 256K for 31B)
  • KV-cache compression compatibility with TurboQuant policies
6. kgemma CLI Integration
  • Update kgemma selection logic to differentiate Gemma3n vs Gemma4 based on config.json model_type
  • Unified ingestion abstraction (analogous to Gemma3nIngestion) for Gemma4
  • tok/s measurement (already present) serves as regression metric
  • Extend smoke-models.json with Gemma4 E2B entry
7. Tests & CI
  • Unit tests:
    • testGemma4ConfigE2B_parsesLayerTypesAndRope()
    • testGemma4Tokenizer_specialTokensPresent_turn_tool_think()
    • testGemma4PromptFormatter_matchesDocsExample()
  • Integration tests:
    • testGemma4LoadAndGenerate_oneStep_temperatureZero() (SafeTensors load + 1-step decode, CPU FP32, deterministic)
  • Smoke tests:
    • Gemma4 E2B added to smoke-models.json, runner via kgemma
    • tok/s performance regression baseline
  • Golden tests: tokenizer parity checks against HF reference, prompt template string equality against official examples

Acceptance Criteria

  • Gemma4ConfigParser correctly parses config.json for E2B, E4B, and 31B model variants
  • Gemma4ModelMetadata contains all required fields: layer_types, rope_parameters, num_kv_shared_layers, max_position_embeddings, global_head_dim
  • Gemma4SafeTensorsWeightLoader loads single-file and sharded SafeTensors without errors for E2B
  • PLE tables are loaded and applied correctly
  • Tokenizer roundtrip (encode -> decode) is stable for all Gemma 4 special tokens
  • bos/eos/pad token IDs match generation_config.json values
  • Gemma4PromptFormatter output matches official documentation examples exactly (string equality)
  • Thinking mode and tool-calling token sequences are correctly formatted
  • <|tool_response> functions as a stop sequence during generation
  • Hybrid attention produces correct outputs: sliding-window layers use local RoPE, global layers use p-RoPE with global_head_dim
  • KV-sharing reduces memory usage for shared layers (measurable)
  • Generation runs without crash on 128K context inputs (E2B/E4B)
  • kgemma CLI auto-detects Gemma4 models and routes to correct runtime
  • Smoke test passes for Gemma4 E2B with measurable tok/s
  • All unit and integration tests pass in CI (allTests)
  • Gemma3n code path and tests remain unaffected

Risks & Mitigations

Risk Mitigation
Tokenizer mismatch (special tokens, left padding) Golden token tests from tokenizer_config.json + reference fixtures; fail-fast validation of bos/eos/pad
Attention semantics (p-RoPE / global_head_dim / KV-sharing) Stepwise activation: sliding-only on short contexts first, then global+RoPE; golden logits for small inputs
Long-context memory Strict KV-sharing + KV compression (TurboQuant policies) as performance phase

Estimated Effort

Component Effort
Config Parser & Metadata High
Weight Loader High
Tokenizer & Special Tokens Medium-High
Prompt Formatter Medium
Hybrid Attention + KV-Cache High
kgemma Integration Medium
Tests & CI Medium
Ngôn ngữ chính
Kotlin
Star
8
Fork
3
Merge trung bình
1 ngày 16 giờ
Pull request đã merge (30 ngày)
48

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của SKaiNET-developers/SKaiNET-transformers

Tất cả issue của SKaiNET-developers/SKaiNET-transformers

Issue tương tự

Thêm issue về Kotlin

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.