From fc5bfe8d7218f900c20a0afa4f08a67f3560af74 Mon Sep 17 00:00:00 2001 From: Cemil ILIK Date: Mon, 15 Jun 2026 18:59:20 +0300 Subject: [PATCH 1/7] docs(reference): fix accuracy drift vs code (post-#63 audit) architecture.md (EN+TR): 18->19 subcommands (+verify-integrity), exit contract 0/1/2/3/4->0/1/2/3/4/5 (+wizard-cancelled), 21->23 Pydantic config models. library_api_reference.md (EN+TR): fix non-existent TrainResult (output_dir->final_model_path, revert_reason->reverted), VerifyResult (entries_checked->entries_count, drop chain_head), AuditReport attrs + detect_pii/secrets examples. configuration-tr.md: +27 missing field rows to reach EN parity. soc2: drop false webhook-HMAC claim. compliance_summary/supply_chain: verify-integrity + CVE-ignore accuracy. usage-tr.md: missing [export]/[chat] extras + tokenizer files. verify_audit: stale v0.5.5/v0.6.x -> post-v0.7.0. data_ingestion_architecture: stale line cites. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/reference/architecture-tr.md | 20 +++++----- docs/reference/architecture.md | 24 ++++++------ docs/reference/compliance_summary-tr.md | 11 ++++-- docs/reference/compliance_summary.md | 3 +- docs/reference/configuration-tr.md | 39 ++++++++++++++++--- docs/reference/data_ingestion_architecture.md | 4 +- docs/reference/library_api_reference-tr.md | 17 ++++---- docs/reference/library_api_reference.md | 17 ++++---- .../soc2_trust_criteria_mapping-tr.md | 4 +- docs/reference/soc2_trust_criteria_mapping.md | 4 +- docs/reference/supply_chain_security-tr.md | 6 +-- docs/reference/supply_chain_security.md | 6 +-- docs/reference/usage-tr.md | 4 ++ docs/reference/verify_audit-tr.md | 10 ++--- docs/reference/verify_audit.md | 6 +-- .../verify_integrity_subcommand-tr.md | 4 +- 16 files changed, 109 insertions(+), 70 deletions(-) diff --git a/docs/reference/architecture-tr.md b/docs/reference/architecture-tr.md index 1269cd7b..540887da 100644 --- a/docs/reference/architecture-tr.md +++ b/docs/reference/architecture-tr.md @@ -8,15 +8,15 @@ ForgeLM modülerlik ve genişletilebilirlik gözetilerek tasarlanmıştır. İş forgelm --config job.yaml │ ├── cli/ → CLI paketi (Faz 15 split) - │ ├── _parser.py → 18 subcommand + global flag + │ ├── _parser.py → 19 subcommand + global flag │ ├── _dispatch.py → Mod yönlendirici - │ ├── _exit_codes.py → 0/1/2/3/4 sözleşmesi + │ ├── _exit_codes.py → 0/1/2/3/4/5 sözleşmesi │ └── subcommands/ → Subcommand-başına handler'lar │ ├── ingest, audit, chat, export, deploy, doctor, │ │ cache, purge, reverse_pii, approve, approvals, │ │ safety_eval, verify_audit, verify_annex_iv, - │ │ verify_gguf, quickstart - ├── config.py → Pydantic doğrulama (21 config modeli) + │ │ verify_gguf, verify_integrity, quickstart + ├── config.py → Pydantic doğrulama (23 config modeli) ├── utils.py → HF kimlik doğrulama ├── model.py → Model + tokenizer + LoRA/PEFT yükleme ├── data.py → Veri seti yükleme + formatlama @@ -43,19 +43,19 @@ ForgeLM/ ├── forgelm/ # Çekirdek Python paketi (~22 tek-dosya modül + 2 alt-paket) │ ├── __init__.py # Hızlı CLI başlatma için lazy import │ ├── cli/ # CLI alt-paketi (Faz 15 split) -│ │ ├── _parser.py # 18 subcommand + global flag +│ │ ├── _parser.py # 19 subcommand + global flag │ │ ├── _dispatch.py # Mod yönlendirici -│ │ ├── _exit_codes.py # Public 0/1/2/3/4 sözleşmesi +│ │ ├── _exit_codes.py # Public 0/1/2/3/4/5 sözleşmesi │ │ └── subcommands/ # Per-subcommand handler modülleri │ │ └── _audit, _ingest, _chat, _export, _deploy, _doctor, │ │ _cache, _purge, _reverse_pii, _approve, _approvals, │ │ _safety_eval, _verify_audit, _verify_annex_iv, -│ │ _verify_gguf, _quickstart +│ │ _verify_gguf, _verify_integrity, _quickstart │ ├── data_audit/ # Audit alt-paketi (Faz 14 split) │ │ └── _orchestrator, _aggregator, _streaming, _simhash, │ │ _minhash, _pii_regex, _pii_ml, _secrets, _quality, │ │ _croissant, _summary, _splits, _types, _optional -│ ├── config.py # 21 Pydantic config modeli +│ ├── config.py # 23 Pydantic config modeli │ ├── data.py # Veri yükleme (SFT/DPO/KTO/GRPO/multimodal) │ ├── ingestion.py # Ham doküman → SFT JSONL (PDF/DOCX/EPUB/TXT/Markdown) │ ├── model.py # Model + LoRA/DoRA/PiSSA + MoE algılama @@ -101,10 +101,10 @@ ForgeLM/ ## Bileşen Detayları ### `cli/` -Orkestratör (Faz 15 split). `_parser.py` 18 subcommand'ı (`audit`, `approve`, `approvals`, `reject`, `cache-models`, `cache-tasks`, `chat`, `deploy`, `doctor`, `export`, `ingest`, `purge`, `quickstart`, `reverse-pii`, `safety-eval`, `verify-annex-iv`, `verify-audit`, `verify-gguf`) artı eski training-mode flag setini kaydeder. `_dispatch.py` `subcommands/` altındaki uygun handler'a yönlendirir. `_exit_codes.py` public 0/1/2/3/4 sözleşmesini tanımlar. +Orkestratör (Faz 15 split). `_parser.py` 19 subcommand'ı (`audit`, `approve`, `approvals`, `reject`, `cache-models`, `cache-tasks`, `chat`, `deploy`, `doctor`, `export`, `ingest`, `purge`, `quickstart`, `reverse-pii`, `safety-eval`, `verify-annex-iv`, `verify-audit`, `verify-gguf`, `verify-integrity`) artı eski training-mode flag setini kaydeder. `_dispatch.py` `subcommands/` altındaki uygun handler'a yönlendirir. `_exit_codes.py` public 0/1/2/3/4/5 sözleşmesini tanımlar (5 = sihirbaz iptal edildi). ### `config.py` -21 Pydantic v2 modeli: ModelConfig, LoraConfigModel, TrainingConfig, DataConfig, DataGovernanceConfig, EvaluationConfig, SafetyConfig, BenchmarkConfig, JudgeConfig, WebhookConfig, DistributedConfig, MergeConfig, ComplianceMetadataConfig, RetentionConfig, RiskAssessmentConfig, MonitoringConfig, MoeConfig, MultimodalConfig, AuthConfig, SyntheticConfig + üst-düzey ForgeConfig. Çapraz alan doğrulaması içerir. +23 Pydantic v2 modeli: ModelConfig, LoraConfigModel, TrainingConfig, DataConfig, DataGovernanceConfig, EvaluationConfig, SafetyConfig, BenchmarkConfig, JudgeConfig, WebhookConfig, DistributedConfig, MergeConfig, ComplianceMetadataConfig, RetentionConfig, RiskAssessmentConfig, MonitoringConfig, MoeConfig, MultimodalConfig, AuthConfig, SyntheticConfig, PipelineStage, PipelineConfig + üst-düzey ForgeConfig. Çapraz alan doğrulaması içerir. ### `data.py` HuggingFace `datasets` kütüphanesi ile arayüz. Veri formatını otomatik algılar (SFT, DPO, KTO, GRPO, multimodal) ve uyumsuzlukta önerili trainer_type ile hata verir. Mix ratio ile çoklu veri seti karıştırma. `tokenizer.apply_chat_template()` ile sohbet şablonları. diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md index d22020ac..d33f09c9 100644 --- a/docs/reference/architecture.md +++ b/docs/reference/architecture.md @@ -8,15 +8,15 @@ ForgeLM is designed with modularity and extensibility in mind. The workflow is b forgelm --config job.yaml │ ├── cli/ → CLI package (Phase 15 split) - │ ├── _parser.py → 18 subcommands + global flags + │ ├── _parser.py → 19 subcommands + global flags │ ├── _dispatch.py → Mode dispatcher - │ ├── _exit_codes.py → 0/1/2/3/4 contract + │ ├── _exit_codes.py → 0/1/2/3/4/5 contract │ └── subcommands/ → Per-subcommand handlers │ ├── ingest, audit, chat, export, deploy, doctor, │ │ cache, purge, reverse_pii, approve, approvals, │ │ safety_eval, verify_audit, verify_annex_iv, - │ │ verify_gguf, quickstart - ├── config.py → Pydantic validation (21 config models) + │ │ verify_gguf, verify_integrity, quickstart + ├── config.py → Pydantic validation (23 config models) ├── utils.py → HF authentication ├── model.py → Load model + tokenizer + LoRA/PEFT ├── data.py → Load + format dataset @@ -43,19 +43,19 @@ ForgeLM/ ├── forgelm/ # Core Python package (~22 single-file modules + 2 sub-packages) │ ├── __init__.py # Lazy imports for fast CLI startup │ ├── cli/ # CLI sub-package (Phase 15 split) -│ │ ├── _parser.py # 18 subcommands + global flags +│ │ ├── _parser.py # 19 subcommands + global flags │ │ ├── _dispatch.py # Mode dispatcher -│ │ ├── _exit_codes.py # Public 0/1/2/3/4 contract +│ │ ├── _exit_codes.py # Public 0/1/2/3/4/5 contract │ │ └── subcommands/ # Per-subcommand handler modules │ │ └── _audit, _ingest, _chat, _export, _deploy, _doctor, │ │ _cache, _purge, _reverse_pii, _approve, _approvals, │ │ _safety_eval, _verify_audit, _verify_annex_iv, -│ │ _verify_gguf, _quickstart +│ │ _verify_gguf, _verify_integrity, _quickstart │ ├── data_audit/ # Data-audit sub-package (Phase 14 split) │ │ └── _orchestrator, _aggregator, _streaming, _simhash, │ │ _minhash, _pii_regex, _pii_ml, _secrets, _quality, │ │ _croissant, _summary, _splits, _types, _optional -│ ├── config.py # 21 Pydantic config models +│ ├── config.py # 23 Pydantic config models │ ├── data.py # Dataset loading (SFT/DPO/KTO/GRPO/multimodal) │ ├── ingestion.py # Raw docs → SFT JSONL (PDF/DOCX/EPUB/TXT/Markdown) │ ├── model.py # Model + LoRA/DoRA/PiSSA + MoE detection @@ -81,7 +81,9 @@ ForgeLM/ │ ├── _version.py # __version__ + __api_version__ (decoupled) │ └── utils.py # Authentication + checkpoint management ├── forgelm/templates/ # 5 quickstart template bundles -├── configs/deepspeed/ # ZeRO-2, ZeRO-3, ZeRO-3+Offload presets +├── configs/ +│ ├── deepspeed/ # ZeRO-2, ZeRO-3, ZeRO-3+Offload presets +│ └── safety_prompts/ # Built-in adversarial prompt library (140 prompts, 6 categories) ├── notebooks/ # 10 Colab-ready Jupyter notebooks ├── tests/ # ~70 test modules ├── tools/ # CI guards: bilingual_parity, anchor_resolution, @@ -100,10 +102,10 @@ ForgeLM/ ## Component Details ### `cli/` -The orchestrator (Phase 15 split). `_parser.py` registers 18 subcommands (`audit`, `approve`, `approvals`, `reject`, `cache-models`, `cache-tasks`, `chat`, `deploy`, `doctor`, `export`, `ingest`, `purge`, `quickstart`, `reverse-pii`, `safety-eval`, `verify-annex-iv`, `verify-audit`, `verify-gguf`) plus the legacy training-mode flag set. `_dispatch.py` routes to the appropriate handler in `subcommands/`. `_exit_codes.py` defines the public 0/1/2/3/4 contract. +The orchestrator (Phase 15 split). `_parser.py` registers 19 subcommands (`audit`, `approve`, `approvals`, `reject`, `cache-models`, `cache-tasks`, `chat`, `deploy`, `doctor`, `export`, `ingest`, `purge`, `quickstart`, `reverse-pii`, `safety-eval`, `verify-annex-iv`, `verify-audit`, `verify-gguf`, `verify-integrity`) plus the legacy training-mode flag set. `_dispatch.py` routes to the appropriate handler in `subcommands/`. `_exit_codes.py` defines the public 0/1/2/3/4/5 contract (5 = wizard cancelled). ### `config.py` -21 Pydantic v2 models providing strict validation for all YAML configuration. Includes cross-field validation (e.g., high-risk classification enforces safety evaluation). Config models cover: model, LoRA, training, data, evaluation, safety, benchmark, judge, webhook, distributed, merge, compliance, retention, risk assessment, monitoring, MoE, multimodal, data governance, and synthetic-data generation. +23 Pydantic v2 models providing strict validation for all YAML configuration. Includes cross-field validation (e.g., high-risk classification enforces safety evaluation). Config models cover: model, LoRA, training, data, evaluation, safety, benchmark, judge, webhook, distributed, merge, compliance, retention, risk assessment, monitoring, MoE, multimodal, data governance, and synthetic-data generation. ### `data.py` Interfaces with HuggingFace `datasets` library. Auto-detects dataset format (SFT, DPO, KTO, GRPO, multimodal) and validates against `trainer_type`. Handles multi-dataset mixing with configurable ratios. Applies chat templates via `tokenizer.apply_chat_template()` with fallback formatting. diff --git a/docs/reference/compliance_summary-tr.md b/docs/reference/compliance_summary-tr.md index cf2b6a1b..0cb9349f 100644 --- a/docs/reference/compliance_summary-tr.md +++ b/docs/reference/compliance_summary-tr.md @@ -31,7 +31,8 @@ ForgeLM kutudan çıktığı gibi şunları ship eder: - **EU AI Act Madde 14** insan-gözetim kapısı: `forgelm approve` / `reject` Madde 14 staging. - **EU AI Act Madde 15** model-bütünlüğü: `compute_artefact_sha256` + - `model_integrity.json`. + `model_integrity.json`; deployment-sonrası doğrulama: + `forgelm verify-integrity`. - **EU AI Act Madde 17** QMS şablonları: `docs/qms/` (Wave 0 baseline + Wave 4 ISO eklemeleri). - **GDPR Madde 15** erişim hakkı: `forgelm reverse-pii`. @@ -103,9 +104,11 @@ Düzenleyicinin sorduğu vs ForgeLM'in cevapladığı: ve chain-key türetimine katılmaz. Genesis manifest sidecar (`audit_log.jsonl.manifest.json`) truncate-and-resume tahrifatını reddeder. - Doğrulama: `forgelm verify-audit [--require-hmac]` zinciri uçtan - uca doğrular; 0/1 ile çıkar (0/1 surface'ı v0.5.5 stabilization - döngüsünde geçerli; v0.6.x backlog'unda `EXIT_INTEGRITY_FAILURE` - ayrımı bekliyor). + uca doğrular; 0 (geçerli) veya 1 (herhangi bir hata — ayrıştırma + hatası, HMAC uyuşmazlığı, manifest sapması, dosya bulunamadı, + seçenek hatası) ile çıkar. Daha zengin 0/1/2/3 exit-code yüzeyi + **trainer** giriş noktasına (`forgelm --config ...`) uygulanır, + `verify-audit`'e değil. ### Madde 14 staging kapısı diff --git a/docs/reference/compliance_summary.md b/docs/reference/compliance_summary.md index a9f56894..51865b5c 100644 --- a/docs/reference/compliance_summary.md +++ b/docs/reference/compliance_summary.md @@ -32,7 +32,8 @@ ForgeLM ships out-of-the-box: - **EU AI Act Article 14** human-oversight gate via `forgelm approve` / `reject` Article 14 staging. - **EU AI Act Article 15** model-integrity via - `compute_artefact_sha256` + `model_integrity.json`. + `compute_artefact_sha256` + `model_integrity.json`; post-deployment + verification via `forgelm verify-integrity`. - **EU AI Act Article 17** QMS templates in `docs/qms/` (Wave 0 baseline + Wave 4 ISO additions). - **GDPR Article 15** right-of-access via `forgelm reverse-pii`. diff --git a/docs/reference/configuration-tr.md b/docs/reference/configuration-tr.md index 5a7221d2..5191b4f9 100644 --- a/docs/reference/configuration-tr.md +++ b/docs/reference/configuration-tr.md @@ -15,7 +15,10 @@ Tam açıklamalı örnek için `config_template.yaml` dosyasına bakın. | `load_in_4bit` | bool | `true` | QLoRA 4-bit NF4 kuantizasyon | | `backend` | string | `"transformers"` | `"transformers"` veya `"unsloth"` (2-5x hızlı, Linux) | | `trust_remote_code` | bool | `false` | Model depolarından özel kod çalıştırma. **Güvenlik riski** | -| `offline` | bool | `false` | İzole mod: HF Hub çağrısı yok | +| `offline` | bool | `false` | İzole mod: HF Hub çağrısı yok. Modeller/veri setleri yerel olmalı | +| `bnb_4bit_use_double_quant` | bool | `true` | Ekstra VRAM tasarrufu için çift kuantizasyon | +| `bnb_4bit_quant_type` | string | `"nf4"` | Kuantizasyon tipi (`"nf4"` veya `"fp4"`) | +| `bnb_4bit_compute_dtype` | string | `"auto"` | Hesaplama dtype'ı: `"auto"`, `"bfloat16"`, `"float16"`, `"float32"` | #### `model.moe` (İsteğe bağlı — MoE modeller) @@ -38,12 +41,15 @@ Tam açıklamalı örnek için `config_template.yaml` dosyasına bakın. | Alan | Tip | Varsayılan | Açıklama | |------|-----|-----------|----------| -| `r` | int | `8` | LoRA rank | +| `r` | int | `8` | LoRA rank. Yüksek = daha fazla parametre | | `alpha` | int | `16` | LoRA ölçekleme faktörü | +| `dropout` | float | `0.1` | Dropout olasılığı | +| `bias` | string | `"none"` | `"none"`, `"all"` veya `"lora_only"` | | `method` | string | `"lora"` | PEFT yöntemi: `"lora"`, `"dora"`, `"pissa"`, `"rslora"` | | `use_dora` | bool | `false` | DoRA (Ağırlık-Ayrıştırılmış LoRA) | | `use_rslora` | bool | `false` | Rank-stabilize LoRA (r>64 için önerilir) | | `target_modules` | list | `["q_proj", "v_proj"]` | LoRA uygulanacak modüller | +| `task_type` | string | `"CAUSAL_LM"` | PEFT için görev tipi | --- @@ -51,13 +57,24 @@ Tam açıklamalı örnek için `config_template.yaml` dosyasına bakın. | Alan | Tip | Varsayılan | Açıklama | |------|-----|-----------|----------| +| `output_dir` | string | `"./checkpoints"` | Checkpoint kayıt dizini | +| `final_model_dir` | string | `"final_model"` | Nihai artefaktlar için alt dizin | +| `merge_adapters` | bool | `false` | Kaydedilmeden önce adapter'ları temel modele birleştir | | `trainer_type` | string | `"sft"` | `"sft"`, `"dpo"`, `"simpo"`, `"kto"`, `"orpo"`, `"grpo"` | | `max_steps` | int | `-1` | Sıkı adım üst sınırı. `-1` = `num_train_epochs` kullanılır; pozitif bir değer epoch'ları geçersiz kılar. | | `num_train_epochs` | int | `3` | Eğitim epoch sayısı (yalnızca `max_steps == -1` iken dikkate alınır). | | `per_device_train_batch_size` | int | `4` | GPU başına batch boyutu | -| `learning_rate` | float | `2e-5` | Öğrenme oranı | +| `gradient_accumulation_steps` | int | `2` | Geri yayılımdan önce biriktirilecek adım sayısı | +| `learning_rate` | float | `2e-5` | Öğrenme oranı (hizalama için daha düşük: 5e-6) | +| `warmup_ratio` | float | `0.1` | Isınma oranı | +| `weight_decay` | float | `0.01` | AdamW ağırlık bozunumu | +| `eval_steps` | int | `200` | Her N adımda bir değerlendir | +| `save_steps` | int | `200` | Her N adımda bir checkpoint kaydet | +| `save_total_limit` | int | `3` | Tutulacak maksimum checkpoint sayısı | | `early_stopping_patience` | int | `3` | Doğrulama kaybı iyileşmeden N değerlendirme sonra dur (yalnızca bir doğrulama bölünmesi varsa etkin). | +| `packing` | bool | `false` | Dizi paketleme (yalnızca SFT) | | `report_to` | string | `"tensorboard"` | `"tensorboard"`, `"wandb"`, `"mlflow"`, `"none"` | +| `run_name` | string | `null` | W&B/MLflow çalışma adı (null ise otomatik üretilir) | #### OOM Recovery (Bellek Hatası Kurtarma) @@ -112,11 +129,13 @@ training: | Alan | Tip | Varsayılan | Kullanan | |------|-----|-----------|---------| | `dpo_beta` | float | `0.1` | DPO sıcaklık | -| `simpo_gamma` | float | `0.5` | SimPO marj | +| `simpo_gamma` | float | `0.5` | SimPO marj terimi | +| `simpo_beta` | float | `2.0` | SimPO ölçekleme | | `kto_beta` | float | `0.1` | KTO kayıp parametresi | | `orpo_beta` | float | `0.1` | ORPO odds ratio ağırlığı | | `grpo_num_generations` | int | `4` | GRPO: prompt başına yanıt | -| `grpo_reward_model` | string | `null` | GRPO: ödül modeli yolu | +| `grpo_max_completion_length` | int | `512` | GRPO: completion başına maksimum token (eski takma ad `grpo_max_new_tokens` kabul edilir) | +| `grpo_reward_model` | string | `null` | GRPO: ödül modeli yolu (HF veya yerel) | --- @@ -235,7 +254,11 @@ uzatmasını engeller. | Alan | Tip | Varsayılan | Açıklama | |------|-----|-----------|----------| | `provider_name` | string | `""` | Kuruluş adı | +| `provider_contact` | string | `""` | İletişim e-postası | +| `system_name` | string | `""` | Yapay zeka sistemi adı | | `intended_purpose` | string | `""` | Modelin amacı | +| `known_limitations` | string | `""` | Kullanılmaması gereken durumlar | +| `system_version` | string | `""` | Sürüm tanımlayıcısı | | `risk_classification` | string | `"minimal-risk"` | 5 EU AI Act `RiskTier` değerinden biri: `"unknown"` (sınıflandırma öncesi yer tutucu), `"minimal-risk"`, `"limited-risk"`, `"high-risk"` (Madde 6 — tam Annex IV dokümantasyonu), `"unacceptable"` (Madde 5 yasaklı uygulama — başlangıçta uyarı bandı yayınlar). | ## `risk_assessment` (İsteğe bağlı — EU AI Act Madde 9) @@ -246,14 +269,18 @@ uzatmasını engeller. | `foreseeable_misuse` | list | `[]` | Öngörülen kötüye kullanım senaryoları | | `risk_category` | string | `"minimal-risk"` | `compliance.risk_classification` ile aynı 5 `RiskTier` değeri: `"unknown"`, `"minimal-risk"`, `"limited-risk"`, `"high-risk"`, `"unacceptable"`. Auto-revert eşiklerini ve Annex IV kapısını etkiler. | | `mitigation_measures` | list | `[]` | Risk azaltma önlemleri | +| `vulnerable_groups_considered` | bool | `false` | Savunmasız gruplar üzerindeki etki değerlendirildi | ## `monitoring` (İsteğe bağlı — EU AI Act Madde 12+17) | Alan | Tip | Varsayılan | Açıklama | |------|-----|-----------|----------| | `enabled` | bool | `false` | İzleme hook'larını etkinleştir | -| `metrics_export` | string | `"none"` | `"none"`, `"prometheus"`, `"datadog"` | +| `endpoint` | string | `""` | İzleme webhook URL'si | +| `endpoint_env` | string | `null` | Endpoint için ortam değişkeni adı | +| `metrics_export` | string | `"none"` | `"none"`, `"prometheus"`, `"datadog"`, `"custom_webhook"` | | `alert_on_drift` | bool | `true` | Model sapmasında uyar | +| `check_interval_hours` | int | `24` | İzleme kontrol aralığı (saat) | ## `distributed` (İsteğe bağlı) diff --git a/docs/reference/data_ingestion_architecture.md b/docs/reference/data_ingestion_architecture.md index 44dbdb6d..bf9914ea 100644 --- a/docs/reference/data_ingestion_architecture.md +++ b/docs/reference/data_ingestion_architecture.md @@ -35,7 +35,7 @@ graph LR ``` Single entry point: [`forgelm.ingestion.ingest_path`](../../forgelm/ingestion.py) -at line `1200`. The CLI subcommand +(currently at line 2193). The CLI subcommand [`forgelm/cli/subcommands/_ingest.py`](../../forgelm/cli/subcommands/_ingest.py) is a thin argparse adapter — it resolves `--all-mask` into the two underlying booleans and delegates everything else to `ingest_path`. @@ -440,7 +440,7 @@ phone. Replacement token: `[REDACTED]`. `_emit_chunk` enforces the order: secrets pass, then PII pass. Two reasons (encoded as a docstring comment in -[`ingestion.py:1098`](../../forgelm/ingestion.py)): +[`ingestion.py:2078`](../../forgelm/ingestion.py)): 1. Secrets are higher-severity than PII. A leaked AWS key in training data is unrecoverable; a phone number is recoverable via opt-out diff --git a/docs/reference/library_api_reference-tr.md b/docs/reference/library_api_reference-tr.md index 73504721..6dd20a8d 100644 --- a/docs/reference/library_api_reference-tr.md +++ b/docs/reference/library_api_reference-tr.md @@ -129,8 +129,9 @@ report = audit_dataset( ) print(f"samples: {report.total_samples}") -print(f"duplicates: {report.duplicate_count}") -print(f"pii findings: {len(report.pii_findings)}") +pairs = report.near_duplicate_summary.get('pairs_per_split', {}) +print(f"near-duplicates: {pairs}") +print(f"pii summary: {report.pii_summary}") # cross_split_overlap dict[str, Any] - anahtar üzerinden erişin print(f"split overlap pairs: {report.cross_split_overlap.get('pairs', {})}") ``` @@ -149,7 +150,7 @@ result = verify_audit_log( if not result.valid: raise SystemExit(f"audit chain broken: {result.reason}") -print(f"verified {result.entries_checked} entries; head={result.chain_head}") +print(f"verified {result.entries_count} entries") ``` ### 3. Uçtan uca eğitim (saf Python, YAML yok) @@ -172,9 +173,9 @@ config = ForgeConfig( trainer = ForgeTrainer(config) result = trainer.train() -print(f"success={result.success} output={result.output_dir}") -if not result.success and result.revert_reason: - print(f"reverted: {result.revert_reason}") +print(f"success={result.success} output={result.final_model_path}") +if not result.success and result.reverted: + print(f"reverted; reason: {result.error}") ``` Yukarıdaki anahtarlar tek **gerekli** olanlardır; geri kalan her şey `forgelm/config.py` varsayılanlarına düşer. `model.name_or_path`, `lora:` bloğu, `data.dataset_name_or_path` ve `training.{trainer_type, output_dir}` Pydantic şeması tarafından zorunlu kılınır; `num_epochs` / `batch_size` kanonik adlar değildir ve `ValidationError` atar. @@ -214,8 +215,8 @@ text = "Contact alice@example.com or use AKIAIOSFODNN7EXAMPLE for the call." pii = detect_pii(text) secrets = detect_secrets(text) -print(f"pii: {[(f.kind, f.span) for f in pii]}") -print(f"secrets: {[(f.kind, f.span) for f in secrets]}") +print(f"pii: {pii}") +print(f"secrets: {secrets}") masked = mask_secrets(mask_pii(text)) print(masked) diff --git a/docs/reference/library_api_reference.md b/docs/reference/library_api_reference.md index a3ee9470..6e2b33e1 100644 --- a/docs/reference/library_api_reference.md +++ b/docs/reference/library_api_reference.md @@ -129,8 +129,9 @@ report = audit_dataset( ) print(f"samples: {report.total_samples}") -print(f"duplicates: {report.duplicate_count}") -print(f"pii findings: {len(report.pii_findings)}") +pairs = report.near_duplicate_summary.get('pairs_per_split', {}) +print(f"near-duplicates: {pairs}") +print(f"pii summary: {report.pii_summary}") # cross_split_overlap is dict[str, Any], access by key print(f"split overlap pairs: {report.cross_split_overlap.get('pairs', {})}") ``` @@ -149,7 +150,7 @@ result = verify_audit_log( if not result.valid: raise SystemExit(f"audit chain broken: {result.reason}") -print(f"verified {result.entries_checked} entries; head={result.chain_head}") +print(f"verified {result.entries_count} entries") ``` ### 3. Train end-to-end (pure Python, no YAML) @@ -172,9 +173,9 @@ config = ForgeConfig( trainer = ForgeTrainer(config) result = trainer.train() -print(f"success={result.success} output={result.output_dir}") -if not result.success and result.revert_reason: - print(f"reverted: {result.revert_reason}") +print(f"success={result.success} output={result.final_model_path}") +if not result.success and result.reverted: + print(f"reverted; reason: {result.error}") ``` The keys above are the **only** required ones; everything else falls back to `forgelm/config.py` defaults. `model.name_or_path`, the `lora:` block, `data.dataset_name_or_path`, and `training.{trainer_type, output_dir}` are required by the Pydantic schema; `num_epochs` / `batch_size` are not the canonical names and would raise `ValidationError`. @@ -214,8 +215,8 @@ text = "Contact alice@example.com or use AKIAIOSFODNN7EXAMPLE for the call." pii = detect_pii(text) secrets = detect_secrets(text) -print(f"pii: {[(f.kind, f.span) for f in pii]}") -print(f"secrets: {[(f.kind, f.span) for f in secrets]}") +print(f"pii: {pii}") +print(f"secrets: {secrets}") masked = mask_secrets(mask_pii(text)) print(masked) diff --git a/docs/reference/soc2_trust_criteria_mapping-tr.md b/docs/reference/soc2_trust_criteria_mapping-tr.md index 6ceed0ad..0466c906 100644 --- a/docs/reference/soc2_trust_criteria_mapping-tr.md +++ b/docs/reference/soc2_trust_criteria_mapping-tr.md @@ -51,7 +51,7 @@ kategoriler engagement-bazında scoplanır. | CC6.7 | Bilgi hareketini kısıtlar | `safe_post` egress discipline; webhook payload curation | | CC6.8 | Yetkisiz yazılımı tespit eder/önler | SBOM; `pip-audit` nightly; `bandit` CI | | CC7.1 | Zafiyetleri tespit eder | `pip-audit` nightly; CVE feed | -| CC7.2 | Sistem bileşenlerini izler | `forgelm verify-audit`; `forgelm verify-gguf`; `safety_trend.jsonl` | +| CC7.2 | Sistem bileşenlerini izler | `forgelm verify-audit`; `forgelm verify-gguf`; `forgelm verify-integrity`; `safety_trend.jsonl` | | CC7.3 | Güvenlik olaylarını değerlendirir | `data.erasure_failed`, `pipeline.failed` olayları `error_class` + `error_message` ile | | CC7.4 | Güvenlik olaylarına yanıt verir | `auto_revert`; `model.reverted` olayı | | CC7.5 | Düzeltici eylemleri tanımlar, geliştirir | `human_approval.rejected`; `sop_change_management.md` | @@ -99,7 +99,7 @@ Güçlü ForgeLM katkısı. | P4.1 Kullanım, saklama ve imha | `retention.staging_ttl_days` (kanonik; eski takma ad `evaluation.staging_ttl_days` v0.5.5 → v0.6.x deprecation penceresi boyunca şeffaf yönlendirir); `forgelm purge --check-policy` | | P5.1 Erişim | `forgelm reverse-pii` Madde 15 scan; salted query-hash | | P5.2 Sorular ve şikayetler | (Operatör-tarafı workflow) | -| P6.1 Üçüncü taraflara açıklama | `safe_post` webhook discipline; HMAC payload signing | +| P6.1 Üçüncü taraflara açıklama | `safe_post` webhook discipline (yalnız TLS, SSRF koruması, yönlendirme reddi); not: webhook gövdeleri HMAC ile imzalanmaz — bkz. ISO 27001 A.8.21 | | P6.2 Üçüncü taraf anlaşmaları | (Operatör DPA'ları) | | P7.1 İhlal bildirimi | `data.erasure_failed`, `audit.classifier_load_failed` olayları | | P7.2 İhlal açıklaması | (Operatör regulator-contact playbook) | diff --git a/docs/reference/soc2_trust_criteria_mapping.md b/docs/reference/soc2_trust_criteria_mapping.md index 02151781..2ccb163c 100644 --- a/docs/reference/soc2_trust_criteria_mapping.md +++ b/docs/reference/soc2_trust_criteria_mapping.md @@ -51,7 +51,7 @@ categories are scoped per-engagement. | CC6.7 | Restricts movement of information | `safe_post` egress discipline; webhook payload curation | | CC6.8 | Detects/prevents unauthorised software | SBOM; `pip-audit` nightly; `bandit` CI | | CC7.1 | Detects vulnerabilities | `pip-audit` nightly; CVE feed | -| CC7.2 | Monitors system components | `forgelm verify-audit`; `forgelm verify-gguf`; `safety_trend.jsonl` | +| CC7.2 | Monitors system components | `forgelm verify-audit`; `forgelm verify-gguf`; `forgelm verify-integrity`; `safety_trend.jsonl` | | CC7.3 | Evaluates security events | `data.erasure_failed`, `pipeline.failed` events with `error_class` + `error_message` | | CC7.4 | Responds to security events | `auto_revert`; `model.reverted` event | | CC7.5 | Identifies, develops corrective actions | `human_approval.rejected`; `sop_change_management.md` | @@ -100,7 +100,7 @@ Strong ForgeLM contribution. | P4.1 Use, retention, and disposal | `retention.staging_ttl_days` (canonical; legacy alias `evaluation.staging_ttl_days` forwards transparently during the v0.5.5 → v0.6.x deprecation window); `forgelm purge --check-policy` | | P5.1 Access | `forgelm reverse-pii` Article 15 scan; salted query-hash | | P5.2 Inquiries and complaints | (Deployer-side workflow) | -| P6.1 Disclosure to third parties | `safe_post` webhook discipline; HMAC payload signing | +| P6.1 Disclosure to third parties | `safe_post` webhook discipline (TLS-only, SSRF guard, redirect refusal); note: webhook bodies are NOT HMAC-signed — see ISO 27001 A.8.21 | | P6.2 Third-party agreements | (Deployer DPAs) | | P7.1 Breach notification | `data.erasure_failed`, `audit.classifier_load_failed` events | | P7.2 Breach disclosure | (Deployer regulator-contact playbook) | diff --git a/docs/reference/supply_chain_security-tr.md b/docs/reference/supply_chain_security-tr.md index 332b7d20..20685599 100644 --- a/docs/reference/supply_chain_security-tr.md +++ b/docs/reference/supply_chain_security-tr.md @@ -133,9 +133,9 @@ annotation olarak loglanır; audit trail görünür kalır. ForgeLM'in kendi nightly'si proje-içi triage için check-in edilmiş bir [`tools/pip_audit_ignores.yaml`](../../tools/pip_audit_ignores.yaml) -taşır (şu an transformers `CVE-2026-1839` artı 2026-05-21 döngüsünden -gelen dokuz no-fix torch advisory'si ve bir OSV-yanlış-sınıflandırılmış -markdown kaydı). Bu dosya yalnız projenin kendi workflow'u tarafından +taşır (şu an **iki** transformers advisory'si (`CVE-2026-1839` ve +`PYSEC-2025-217` / `CVE-2025-14929`), dokuz no-fix torch advisory'si ve +bir OSV-yanlış-sınıflandırılmış markdown kaydı). Bu dosya yalnız projenin kendi workflow'u tarafından `--ignores` ile tüketilir; deployer'lar miras almaz. Her release cycle'da gözden geçirilir. diff --git a/docs/reference/supply_chain_security.md b/docs/reference/supply_chain_security.md index 91057a6a..398e3f8a 100644 --- a/docs/reference/supply_chain_security.md +++ b/docs/reference/supply_chain_security.md @@ -133,9 +133,9 @@ the run summary so the audit trail stays visible. ForgeLM's own nightly does carry a checked-in [`tools/pip_audit_ignores.yaml`](../../tools/pip_audit_ignores.yaml) for -project-internal triage (currently transformers `CVE-2026-1839` plus -nine no-fix torch advisories and one OSV-misclassified markdown -record from the 2026-05-21 cycle). That file is consumed only by the +project-internal triage (currently **two** transformers advisories +(`CVE-2026-1839` and `PYSEC-2025-217` / `CVE-2025-14929`), nine +no-fix torch advisories, and one OSV-misclassified markdown record). That file is consumed only by the project's own workflow via `--ignores`; deployers do not inherit it. Review at every release cycle. diff --git a/docs/reference/usage-tr.md b/docs/reference/usage-tr.md index e236b3fc..5d6dc4bd 100644 --- a/docs/reference/usage-tr.md +++ b/docs/reference/usage-tr.md @@ -22,6 +22,8 @@ pip install -e ".[eval]" # lm-evaluation-harness pip install -e ".[tracking]" # W&B deney takibi pip install -e ".[distributed]" # DeepSpeed çoklu GPU pip install -e ".[merging]" # native model birleştirme (TIES/DARE/SLERP — ekstra bağımlılık yok) +pip install -e ".[export]" # GGUF export (llama-cpp-python, Windows-dışı) +pip install -e ".[chat]" # forgelm chat'te Rich render'lama ``` ## Kimlik Doğrulama @@ -256,6 +258,8 @@ checkpoints/ ├── final_model/ │ ├── adapter_config.json │ ├── adapter_model.safetensors +│ ├── tokenizer.json +│ ├── tokenizer_config.json │ ├── README.md # Otomatik model kartı │ ├── deployer_instructions.md # Dağıtıcı rehberi (Madde 13) │ └── model_integrity.json # SHA-256 checksum'lar (Madde 15) diff --git a/docs/reference/verify_audit-tr.md b/docs/reference/verify_audit-tr.md index 09d7c6fc..97d85d7a 100644 --- a/docs/reference/verify_audit-tr.md +++ b/docs/reference/verify_audit-tr.md @@ -20,7 +20,7 @@ forgelm verify-audit [--hmac-secret-env VAR] [--require-hmac] | Bayrak | Varsayılan | Açıklama | |---|---|---| | `--hmac-secret-env VAR` | `FORGELM_AUDIT_SECRET` | Log yazımı sırasında kullanılan HMAC sırrını taşıyan ortam değişkeninin adı. Değişken set edildiğinde satır başına `_hmac` etiketleri doğrulanır; aksi halde sadece SHA-256 zinciri kontrol edilir. | -| `--require-hmac` | `False` | Sıkı mod. Yapılandırılmış env var set değilse `1`, herhangi bir satırda `_hmac` alanı eksikse yine `1` ile çıkar. Her kaydın HMAC ile imzalı olması gereken regüle CI pipeline'larında kullanın. (Aşağıdaki "Çıkış kodları" tablosuna bakın — `EXIT_CONFIG_ERROR=1` v0.5.5 stabilizasyon dönemi boyunca hem seçenek hatalarını hem de bütünlük arızalarını kapsıyor; ayrı bir `EXIT_INTEGRITY_FAILURE` sabiti v0.6.x'e ertelendi.) | +| `--require-hmac` | `False` | Sıkı mod. Yapılandırılmış env var set değilse `1`, herhangi bir satırda `_hmac` alanı eksikse yine `1` ile çıkar. Her kaydın HMAC ile imzalı olması gereken regüle CI pipeline'larında kullanın. (Aşağıdaki "Çıkış kodları" tablosuna bakın — `EXIT_CONFIG_ERROR=1` şu an hem seçenek hatalarını hem de bütünlük arızalarını kapsıyor; ayrı bir `EXIT_INTEGRITY_FAILURE` sabiti v0.7.0 sonrası backlog'a ertelendi.) | | `-q`, `--quiet` | _kapalı_ | INFO loglarını bastırır. | | `--log-level {DEBUG,INFO,WARNING,ERROR}` | `INFO` | Log ayrıntı seviyesi. | | `-h`, `--help` | — | Argparse yardımını gösterir ve çıkar. | @@ -30,15 +30,15 @@ forgelm verify-audit [--hmac-secret-env VAR] [--require-hmac] | Kod | Anlam | |---|---| | `0` | `EXIT_SUCCESS` — SHA-256 zinciri (ve doğrulandığında HMAC etiketleri) uçtan uca bütün. | -| `1` | `EXIT_CONFIG_ERROR` — v0.5.5 stabilizasyon dönemi boyunca **hem** seçenek/kullanım hatalarını (eksik log dosyası, `--require-hmac` setken env var unset, hatalı satırda JSON decode hatası) **hem** de bütünlük arızalarını (zincir kopması, HMAC uyuşmazlığı, manifest uyuşmazlığı, `--require-hmac` altında eksik `_hmac` satırı) kapsar. | +| `1` | `EXIT_CONFIG_ERROR` — **hem** seçenek/kullanım hatalarını (eksik log dosyası, `--require-hmac` setken env var unset, hatalı satırda JSON decode hatası) **hem** de bütünlük arızalarını (zincir kopması, HMAC uyuşmazlığı, manifest uyuşmazlığı, `--require-hmac` altında eksik `_hmac` satırı) kapsar. | -> **Gelecek deprecation notu.** Ayrı bir `EXIT_VALIDATION_ERROR` / `EXIT_INTEGRITY_FAILURE` sabiti v0.6.x backlog'unda. O zamana kadar CI kapılarında `verify-audit`'ten gelen herhangi bir non-zero exit'i "bu yapımı promote etme" olarak kabul edin — dispatcher şu an seçenek hatalarını bütünlük arızalarından kod ile ayırt etmiyor. Yetkili sözleşme `_verify_audit.py` docstring'inde (`_run_verify_audit_cmd` docstring). +> **Gelecek deprecation notu.** Ayrı bir `EXIT_VALIDATION_ERROR` / `EXIT_INTEGRITY_FAILURE` sabiti v0.7.0 sonrası backlog'unda. O zamana kadar CI kapılarında `verify-audit`'ten gelen herhangi bir non-zero exit'i "bu yapımı promote etme" olarak kabul edin — dispatcher şu an seçenek hatalarını bütünlük arızalarından kod ile ayırt etmiyor. Yetkili sözleşme `_verify_audit.py` docstring'inde (`_run_verify_audit_cmd` docstring). Kodlar dispatcher tarafından `_run_verify_audit_cmd` (`forgelm/cli/subcommands/_verify_audit.py`) satırlarından emit edilir. ## Emit edilen audit event'leri -`forgelm verify-audit` **salt-okunur bir doğrulayıcıdır** ve `audit_log.jsonl`'a **hiçbir** kayıt eklemez. Yalnızca zinciri inceler. Doğrulanan log'un *içinde* görünen event'ler [audit_event_catalog.md](audit_event_catalog-tr.md)'de kataloglanmıştır (verify-audit'in yürüdüğü `_hmac`, `prev_hash` ve `run_id` alanları için Ortak zarf satırına bakın). +`forgelm verify-audit` **salt-okunur bir doğrulayıcıdır** ve `audit_log.jsonl`'a **hiçbir** kayıt eklemez. Yalnızca zinciri inceler. Doğrulanan log'un *içinde* görünen event'ler [audit_event_catalog-tr.md](audit_event_catalog-tr.md)'de kataloglanmıştır (verify-audit'in yürüdüğü `_hmac`, `prev_hash` ve `run_id` alanları için Ortak zarf satırına bakın). ## Örnekler @@ -99,7 +99,7 @@ $ echo $? ## Bkz. -- [`audit_event_catalog.md`](audit_event_catalog-tr.md) — bu komutun doğruladığı log'un *içinde* görünen event'ler. +- [`audit_event_catalog-tr.md`](audit_event_catalog-tr.md) — bu komutun doğruladığı log'un *içinde* görünen event'ler. - [`verify_annex_iv_subcommand.md`](verify_annex_iv_subcommand-tr.md) — Annex IV teknik dokümantasyon artifact'ı için kardeş doğrulayıcı. - [`verify_gguf_subcommand.md`](verify_gguf_subcommand-tr.md) — export edilmiş GGUF model dosyaları için kardeş doğrulayıcı. - [Audit Log kullanım kılavuzu sayfası](../usermanuals/tr/compliance/audit-log.md) — log'un kendisine dair operatör-odaklı kılavuz. diff --git a/docs/reference/verify_audit.md b/docs/reference/verify_audit.md index d3ab6008..3cdf051b 100644 --- a/docs/reference/verify_audit.md +++ b/docs/reference/verify_audit.md @@ -20,7 +20,7 @@ forgelm verify-audit [--hmac-secret-env VAR] [--require-hmac] | Flag | Default | Description | |---|---|---| | `--hmac-secret-env VAR` | `FORGELM_AUDIT_SECRET` | Name of the environment variable that holds the HMAC secret used at log-write time. When the variable is set, per-line `_hmac` tags are validated; when unset, only the SHA-256 chain is checked. | -| `--require-hmac` | `False` | Strict mode. Exit `1` if the configured env var is unset, and exit `1` if any line lacks an `_hmac` field. Use this in regulated CI pipelines where every entry must be HMAC-authenticated. (See "Exit codes" below — `EXIT_CONFIG_ERROR=1` covers both option errors and integrity failures during the v0.5.5 stabilisation cycle; a dedicated `EXIT_INTEGRITY_FAILURE` constant is deferred to v0.6.x.) | +| `--require-hmac` | `False` | Strict mode. Exit `1` if the configured env var is unset, and exit `1` if any line lacks an `_hmac` field. Use this in regulated CI pipelines where every entry must be HMAC-authenticated. (See "Exit codes" below — `EXIT_CONFIG_ERROR=1` currently covers both option errors and integrity failures; a dedicated `EXIT_INTEGRITY_FAILURE` constant is deferred to the post-v0.7.0 backlog.) | | `-q`, `--quiet` | _off_ | Suppress INFO logs. | | `--log-level {DEBUG,INFO,WARNING,ERROR}` | `INFO` | Set logging verbosity. | | `-h`, `--help` | — | Show argparse help and exit. | @@ -30,9 +30,9 @@ forgelm verify-audit [--hmac-secret-env VAR] [--require-hmac] | Code | Meaning | |---|---| | `0` | `EXIT_SUCCESS` — the SHA-256 chain (and HMAC tags, when verified) is intact end-to-end. | -| `1` | `EXIT_CONFIG_ERROR` — covers **both** option/usage errors (missing log file, `--require-hmac` set with the env var unset, JSON decode error on a malformed line) **and** integrity failures (chain break, HMAC mismatch, manifest mismatch, missing `_hmac` line under `--require-hmac`) during the v0.5.5 stabilisation cycle. | +| `1` | `EXIT_CONFIG_ERROR` — covers **both** option/usage errors (missing log file, `--require-hmac` set with the env var unset, JSON decode error on a malformed line) **and** integrity failures (chain break, HMAC mismatch, manifest mismatch, missing `_hmac` line under `--require-hmac`). | -> **Future deprecation note.** A dedicated `EXIT_VALIDATION_ERROR` / `EXIT_INTEGRITY_FAILURE` constant is on the v0.6.x backlog. Until then, treat any non-zero exit from `verify-audit` as "do not promote this build" in CI gates — the dispatcher does not currently distinguish option errors from integrity failures by code. The `_verify_audit.py` docstring (`_run_verify_audit_cmd` docstring) holds the authoritative contract. +> **Future deprecation note.** A dedicated `EXIT_VALIDATION_ERROR` / `EXIT_INTEGRITY_FAILURE` constant is on the post-v0.7.0 backlog. Until then, treat any non-zero exit from `verify-audit` as "do not promote this build" in CI gates — the dispatcher does not currently distinguish option errors from integrity failures by code. The `_verify_audit.py` docstring (`_run_verify_audit_cmd` docstring) holds the authoritative contract. The codes are emitted by the dispatcher at `_run_verify_audit_cmd` (`forgelm/cli/subcommands/_verify_audit.py`). diff --git a/docs/reference/verify_integrity_subcommand-tr.md b/docs/reference/verify_integrity_subcommand-tr.md index b219a928..d402f86e 100644 --- a/docs/reference/verify_integrity_subcommand-tr.md +++ b/docs/reference/verify_integrity_subcommand-tr.md @@ -44,7 +44,7 @@ Kodlar `forgelm/cli/subcommands/_verify_integrity.py::_run_verify_integrity_cmd` ## Emit edilen audit event'leri -`forgelm verify-integrity` **salt-okunur bir doğrulayıcıdır** ve `audit_log.jsonl`'a **hiçbir** girdi emit etmez. Bütünlük-manifestinin *üretimini* (doğrulamasını değil) işaret eden olaylar çalıştırma düzeyindeki eğitim olaylarına biner; bkz. [audit_event_catalog.md](audit_event_catalog-tr.md). +`forgelm verify-integrity` **salt-okunur bir doğrulayıcıdır** ve `audit_log.jsonl`'a **hiçbir** girdi emit etmez. Bütünlük-manifestinin *üretimini* (doğrulamasını değil) işaret eden olaylar çalıştırma düzeyindeki eğitim olaylarına biner; bkz. [audit_event_catalog-tr.md](audit_event_catalog-tr.md). ## Örnekler @@ -95,7 +95,7 @@ $ echo $? ## Bkz. -- [`audit_event_catalog.md`](audit_event_catalog-tr.md) — kanonik olay sözcük dağarcığı. +- [`audit_event_catalog-tr.md`](audit_event_catalog-tr.md) — kanonik olay sözcük dağarcığı. - [`verify_gguf_subcommand.md`](verify_gguf_subcommand-tr.md) — export edilen GGUF dosyaları için eşlik eden doğrulayıcı. - [`verify_annex_iv_subcommand.md`](verify_annex_iv_subcommand-tr.md) — Annex IV teknik-dokümantasyon yapıtı için eşlik eden doğrulayıcı. - `forgelm.cli.subcommands._verify_integrity.verify_integrity` — entegratörlerin CLI'den geçmeden doğrudan çağırdığı kütüphane giriş noktası. From baab6866fe365eb41604ed3ffd56e0dcb4d6e4b4 Mon Sep 17 00:00:00 2001 From: Cemil ILIK Date: Mon, 15 Jun 2026 18:59:23 +0300 Subject: [PATCH 2/7] docs(usermanuals): fix phantom config blocks + add verify-integrity page (post-#63 audit) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove non-existent YAML blocks users would hit ValidationError on: galore:/datasets:/output: (training/galore, long-context), deployment: (deploy-targets), and fix field names (use_unsloth->model.backend, training.batch_size->per_device_train_batch_size, rope_scaling/sliding_window_attention under training:, GaLore rank default 256->128). configuration.md: 12->15 top-level blocks. benchmarks: floors{} -> min_score scalar. Remove non-existent forgelm batch-chat. NEW: compliance/verify-integrity.md (EN+TR) + _meta.yaml entry — the Art.15 model-integrity verifier now has its own user-manual page (fixes the dangling see-also from verify-audit). EN<->TR kept in sync throughout. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/usermanuals/_meta.yaml | 8 ++ docs/usermanuals/en/compliance/gdpr.md | 27 +--- .../en/compliance/human-oversight.md | 3 +- docs/usermanuals/en/compliance/model-card.md | 21 +-- .../usermanuals/en/compliance/verify-audit.md | 9 +- .../en/compliance/verify-integrity.md | 114 ++++++++++++++++ docs/usermanuals/en/data/audit.md | 17 +-- docs/usermanuals/en/data/deduplication.md | 25 ++-- docs/usermanuals/en/data/ingestion.md | 2 +- .../usermanuals/en/data/language-detection.md | 11 +- docs/usermanuals/en/data/leakage.md | 16 +-- docs/usermanuals/en/data/pii-masking.md | 15 +-- docs/usermanuals/en/data/pii-ml.md | 2 +- docs/usermanuals/en/data/quality-filter.md | 46 ++----- docs/usermanuals/en/deployment/chat.md | 4 +- .../en/deployment/deploy-targets.md | 28 ++-- docs/usermanuals/en/evaluation/benchmarks.md | 53 ++++---- .../en/getting-started/first-run.md | 2 +- docs/usermanuals/en/operations/cicd.md | 2 +- .../en/operations/iso-soc2-deployer.md | 2 +- .../usermanuals/en/operations/supply-chain.md | 2 +- .../usermanuals/en/reference/configuration.md | 124 +++++++++++------- docs/usermanuals/en/training/distributed.md | 6 +- docs/usermanuals/en/training/galore.md | 36 +++-- docs/usermanuals/en/training/long-context.md | 18 +-- docs/usermanuals/en/training/lora.md | 2 +- docs/usermanuals/tr/compliance/gdpr.md | 27 +--- .../tr/compliance/human-oversight.md | 3 +- docs/usermanuals/tr/compliance/model-card.md | 21 +-- .../usermanuals/tr/compliance/verify-audit.md | 9 +- .../tr/compliance/verify-integrity.md | 114 ++++++++++++++++ docs/usermanuals/tr/concepts/data-formats.md | 4 +- docs/usermanuals/tr/data/audit.md | 17 +-- docs/usermanuals/tr/data/deduplication.md | 25 ++-- docs/usermanuals/tr/data/ingestion.md | 2 +- .../usermanuals/tr/data/language-detection.md | 11 +- docs/usermanuals/tr/data/leakage.md | 16 +-- docs/usermanuals/tr/data/pii-masking.md | 15 +-- docs/usermanuals/tr/data/pii-ml.md | 2 +- docs/usermanuals/tr/data/quality-filter.md | 52 +++----- docs/usermanuals/tr/deployment/chat.md | 4 +- .../tr/deployment/deploy-targets.md | 28 ++-- docs/usermanuals/tr/evaluation/benchmarks.md | 55 ++++---- .../tr/getting-started/first-run.md | 2 +- docs/usermanuals/tr/operations/cicd.md | 2 +- .../tr/operations/iso-soc2-deployer.md | 2 +- .../usermanuals/tr/operations/supply-chain.md | 2 +- .../usermanuals/tr/reference/configuration.md | 124 +++++++++++------- docs/usermanuals/tr/training/distributed.md | 6 +- docs/usermanuals/tr/training/galore.md | 36 +++-- docs/usermanuals/tr/training/long-context.md | 18 +-- docs/usermanuals/tr/training/lora.md | 2 +- docs/usermanuals/tr/training/simpo.md | 1 + 53 files changed, 665 insertions(+), 530 deletions(-) create mode 100644 docs/usermanuals/en/compliance/verify-integrity.md create mode 100644 docs/usermanuals/tr/compliance/verify-integrity.md diff --git a/docs/usermanuals/_meta.yaml b/docs/usermanuals/_meta.yaml index 8a1b7e09..b792c55d 100644 --- a/docs/usermanuals/_meta.yaml +++ b/docs/usermanuals/_meta.yaml @@ -387,6 +387,14 @@ sections: fr: Vérifier la chaîne d'audit es: Verificar la cadena de auditoría zh: 验证审计链 + - id: verify-integrity + title: + en: Verify Model Integrity + tr: Model Bütünlüğünü Doğrula + de: Modellintegrität verifizieren + fr: Vérifier l'intégrité du modèle + es: Verificar la integridad del modelo + zh: 验证模型完整性 - id: operations icon: server diff --git a/docs/usermanuals/en/compliance/gdpr.md b/docs/usermanuals/en/compliance/gdpr.md index 983322cd..d8783dbe 100644 --- a/docs/usermanuals/en/compliance/gdpr.md +++ b/docs/usermanuals/en/compliance/gdpr.md @@ -53,12 +53,9 @@ These reports flow into the Annex IV bundle. When a regulator asks "what persona ForgeLM doesn't retain raw user data — it produces JSONL artifacts you control. For automated retention enforcement: ```yaml -ingestion: - retention: - raw_documents: - ttl_days: 90 # auto-delete originals after N days - audit_reports: - ttl_days: 365 +retention: + raw_documents_retention_days: 90 # auto-delete originals after N days + ephemeral_artefact_retention_days: 365 ``` (The actual deletion is your storage layer's responsibility; ForgeLM just records the intended TTL in the audit log.) @@ -105,26 +102,14 @@ For high-risk processing, GDPR Art. 35 requires a DPIA. ForgeLM doesn't write yo - Risk classification → from `compliance.risk_classification`. - Personal data inventory → from `data_audit_report.json`. -- Mitigations applied → from `compliance.risk_assessment.mitigations`. -- Residual risks → from `compliance.risk_assessment.residual_risks`. +- Mitigations applied → from `risk_assessment.mitigation_measures`. +- Foreseeable misuse / residual risks → from `risk_assessment.foreseeable_misuse` (free-text list; a dedicated residual_risks field does not exist in the schema). For DPIA work, pair the inputs above with the QMS [risk-treatment plan](https://github.com/HodeTech/ForgeLM/blob/main/docs/qms/risk_treatment_plan.md) and the [Statement of Applicability](https://github.com/HodeTech/ForgeLM/blob/main/docs/qms/statement_of_applicability.md) (GitHub QMS templates shipped with the toolkit). A dedicated DPIA template is on the roadmap; the risk-treatment plan covers the same ground for now. ## Configuration reference -```yaml -compliance: - data_protection: - framework: "GDPR" # GDPR | KVKK | both - lawful_basis: "legitimate-interest" # consent | contract | legal-obligation | ... - purpose: "Customer-support assistant for X" - data_controller: "Acme Corp" - data_subjects: "telecom customers" - retention_basis: "model lifecycle (~3 years) plus audit period" - international_transfers: - enabled: false # set true if training data crosses borders - safeguards: "Standard Contractual Clauses 2021/914" -``` +ForgeLM has no YAML surface for GDPR legal metadata (lawful basis, data controller, etc.) — these attributes belong in your organisation's legal documentation and DPIA, not in `forgelm/config.py`. The `ComplianceMetadataConfig` schema (`compliance:` top-level block) accepts only: `provider_name`, `provider_contact`, `system_name`, `intended_purpose`, `known_limitations`, `system_version`, and `risk_classification`. A `compliance.data_protection` sub-block does not exist and will be rejected by Pydantic at startup (`extra="forbid"`). ## Common pitfalls diff --git a/docs/usermanuals/en/compliance/human-oversight.md b/docs/usermanuals/en/compliance/human-oversight.md index 3e808de9..373f7db2 100644 --- a/docs/usermanuals/en/compliance/human-oversight.md +++ b/docs/usermanuals/en/compliance/human-oversight.md @@ -82,8 +82,7 @@ Every approval (or rejection) appends to `audit_log.jsonl`: ```json { - "ts": "2026-04-29T15:18:42Z", - "seq": 87, + "timestamp": "2026-04-29T15:18:42Z", "event": "human_approval.granted", "run_id": "abc123", "approver": "ci-reviewer@example", diff --git a/docs/usermanuals/en/compliance/model-card.md b/docs/usermanuals/en/compliance/model-card.md index 63808231..95f7f4a0 100644 --- a/docs/usermanuals/en/compliance/model-card.md +++ b/docs/usermanuals/en/compliance/model-card.md @@ -29,7 +29,7 @@ The output is a Markdown file at `checkpoints/run/README.md` ready to upload to ```markdown # Acme Customer Support v1.2.0 -Customer-support assistant fine-tuned from Qwen2.5-7B-Instruct using ForgeLM 0.5.5. +Customer-support assistant fine-tuned from Qwen2.5-7B-Instruct using ForgeLM 0.7.0. ## Model details @@ -112,27 +112,14 @@ If you use this model, please cite: title = {Acme Customer Support v1.2.0}, author = {Acme Corp}, year = {2026}, - note = {Fine-tuned with ForgeLM 0.5.5} + note = {Fine-tuned with ForgeLM 0.7.0} } ``` ``` ## Configuration -```yaml -output: - model_card: true # default - model_card_template: null # custom Jinja2 template path -``` - -For custom branding, override the default template: - -```yaml -output: - model_card_template: "templates/acme-card.j2" -``` - -The template gets the same data as the default — just renders differently. +Model card generation is automatic after every successful run — there is no YAML knob to enable or disable it. There is no `output:` top-level config block in ForgeLM; adding one will be rejected by Pydantic validation (`extra="forbid"`). If you need to customise the card template, check the current schema in `forgelm/config.py` for the actual field name before documenting it. ## Manual additions @@ -156,4 +143,4 @@ For HuggingFace Hub publication, ForgeLM's model card uses HuggingFace's standar - [Annex IV](#/compliance/annex-iv) — the Article 11 sibling. - [Compliance Overview](#/compliance/overview) — context. -- [Configuration Reference](#/reference/configuration) — `output.model_card` field. +- [Configuration Reference](#/reference/configuration) — `compliance.*` fields used as model card inputs. diff --git a/docs/usermanuals/en/compliance/verify-audit.md b/docs/usermanuals/en/compliance/verify-audit.md index 2211aea1..27c7a6d8 100644 --- a/docs/usermanuals/en/compliance/verify-audit.md +++ b/docs/usermanuals/en/compliance/verify-audit.md @@ -40,7 +40,7 @@ sequenceDiagram ## Quick start ```shell -$ forgelm verify-audit checkpoints/run/compliance/audit_log.jsonl +$ forgelm verify-audit checkpoints/run/audit_log.jsonl OK: 87 entries verified ``` @@ -48,7 +48,7 @@ For HMAC-authenticated logs, set the operator secret first: ```shell $ FORGELM_AUDIT_SECRET="$(cat /run/secrets/audit-secret)" \ - forgelm verify-audit checkpoints/run/compliance/audit_log.jsonl + forgelm verify-audit checkpoints/run/audit_log.jsonl OK: 87 entries verified (HMAC validated) ``` @@ -61,7 +61,7 @@ When every entry must be HMAC-authenticated (an enterprise audit profile), pass ```shell $ FORGELM_AUDIT_SECRET="$(cat /run/secrets/audit-secret)" \ forgelm verify-audit --require-hmac \ - checkpoints/run/compliance/audit_log.jsonl + checkpoints/run/audit_log.jsonl ``` Strict mode flips two safety nets: @@ -92,7 +92,7 @@ FAIL at line 53: prev_hash mismatch — chain break suggests entry was inserted, A bare reason without a line number means the failure happened before the chain walk (e.g. missing genesis manifest, JSON decode error on line 1): ```text -FAIL: manifest present but unreadable at 'checkpoints/run/compliance/audit_log.jsonl.manifest.json': … +FAIL: manifest present but unreadable at 'checkpoints/run/audit_log.jsonl.manifest.json': … ``` Either way, exit code is `1`. Investigate before treating the log as evidence. @@ -127,4 +127,5 @@ Either way, exit code is `1`. Investigate before treating the log as evidence. - [Audit Log](#/compliance/audit-log) — operator-facing primer on the log this command verifies. - [Annex IV](#/compliance/annex-iv) — the technical-documentation artifact whose verifier (`forgelm verify-annex-iv`) shares this verifier's design pattern. - [Verify GGUF](#/deployment/verify-gguf) — companion verifier on the deployment-integrity surface. +- [Verify Model Integrity](#/compliance/verify-integrity) — companion verifier for the Article 15 model-integrity manifest. - [`audit_event_catalog.md`](https://github.com/HodeTech/ForgeLM/blob/main/docs/reference/audit_event_catalog.md) — events that appear *inside* the verified log (GitHub source). diff --git a/docs/usermanuals/en/compliance/verify-integrity.md b/docs/usermanuals/en/compliance/verify-integrity.md new file mode 100644 index 00000000..7d2ef2a3 --- /dev/null +++ b/docs/usermanuals/en/compliance/verify-integrity.md @@ -0,0 +1,114 @@ +--- +title: Verify Model Integrity +description: Re-hash a trained model directory against its SHA-256 integrity manifest (model_integrity.json) to prove no artifact changed, was removed, or was added since training. +--- + +# Verify Model Integrity + +`forgelm verify-integrity` is the read-only verifier paired with the Article 15 model-integrity manifest. The compliance export writes `model_integrity.json` next to the final model at training time, recording the SHA-256 and byte size of every artifact. `verify-integrity` re-walks the directory, re-computes each hash, and reports any file that was **changed**, **removed**, or **added** since the manifest was generated. It is the model-artifact counterpart to [`verify-audit`](#/compliance/verify-audit), which verifies the audit *log* rather than the model *weights*. + +## When to use it + +- **Before deploying or shipping a trained model.** A clean `verify-integrity` exit proves the bytes you are about to serve are the bytes you trained and recorded. +- **After moving a model between machines or storage tiers.** Any silent corruption in transit surfaces as a changed/removed artifact. +- **In CI/CD release gates.** Run after the compliance export; fail the release on a non-zero exit. +- **As part of a periodic compliance sweep.** A scheduled re-verification of archived models surfaces tampering or bit-rot early. + +## How it works + +```mermaid +sequenceDiagram + participant CI as CI / operator + participant Verify as forgelm verify-integrity + participant Manifest as model_integrity.json + participant Dir as model directory + + CI->>Verify: verify-integrity MODEL_DIR + Verify->>Manifest: load recorded {file, sha256, size_bytes} + Verify->>Dir: walk artifacts (manifest file itself excluded) + loop per artifact + Verify->>Verify: recompute sha256, compare to manifest + end + Verify->>Verify: classify changed / removed / added + Verify-->>CI: exit 0 (all match) / 1 (mismatch or input error) / 2 (runtime I/O failure) +``` + +## Quick start + +```shell +$ forgelm verify-integrity ./checkpoints/final_model +OK: all 12 recorded artifact(s) present and unchanged. +``` + +Machine-readable output for CI: + +```shell +$ forgelm verify-integrity ./checkpoints/final_model --output-format json +``` + +```json +{ + "success": true, + "valid": true, + "reason": "All 12 recorded artifact(s) present and unchanged.", + "changed": [], + "removed": [], + "added": [], + "verified_count": 12, + "path": "/work/checkpoints/final_model" +} +``` + +## Detailed usage + +### Reading a mismatch + +When an artifact no longer matches the manifest, the diff lists are populated and the command exits `1`: + +```json +{ + "success": false, + "valid": false, + "reason": "Model artifacts do not match model_integrity.json: 1 changed, 1 removed.", + "changed": ["adapter_model.safetensors"], + "removed": ["tokenizer.model"], + "added": [], + "verified_count": 10, + "path": "/work/checkpoints/final_model" +} +``` + +- `changed` — artifacts whose SHA-256 no longer matches the manifest. +- `removed` — artifacts recorded in the manifest but absent on disk. +- `added` — on-disk files not recorded in the manifest (the manifest file itself is always excluded from the walk). + +### Exit-code summary + +| Code | Meaning | +|---|---| +| `0` | Every recorded artifact is present and unchanged, and no extra files exist. | +| `1` | Integrity mismatch (changed / removed / added file) **or** operator / input error — missing path, path is a file not a directory, manifest not found, malformed JSON, non-list `artifacts`, or a manifest entry path that escapes the model directory. | +| `2` | Genuine runtime I/O failure on a reachable path (read error, permission denied mid-walk). | + +The runtime-error envelope (exit `2`) emits only `{"success": false, "error": "…"}` — branch on `success` first, then inspect `valid` and the diff lists. + +## Common pitfalls + +:::warn +**Treating a missing `model_integrity.json` as benign.** Without the manifest there is nothing to verify against — `verify-integrity` exits `1`, not `0`. Confirm the compliance export wrote the manifest before relying on this gate. +::: + +:::warn +**Verifying after a re-quantisation or re-export.** Producing a GGUF or merged variant changes the bytes; that model needs its own freshly-generated manifest. Do not verify a converted artifact against the original training manifest. +::: + +:::tip +**Pin the verifier in CI before any deploy step.** Wire `forgelm verify-integrity --output-format json` as a hard gate after the compliance export. A non-zero exit should fail the release pipeline. +::: + +## See also + +- [Verify Audit Chain](#/compliance/verify-audit) — companion verifier for the Article 12 audit *log* (this one covers the model *weights*). +- [Annex IV](#/compliance/annex-iv) — the technical-documentation artifact exported alongside the integrity manifest. +- [Verify GGUF](#/deployment/verify-gguf) — integrity verifier for an exported GGUF model file. +- [`verify_integrity_subcommand.md`](https://github.com/HodeTech/ForgeLM/blob/main/docs/reference/verify_integrity_subcommand.md) — full flag-level reference (GitHub source). diff --git a/docs/usermanuals/en/data/audit.md b/docs/usermanuals/en/data/audit.md index ddc01495..240b879f 100644 --- a/docs/usermanuals/en/data/audit.md +++ b/docs/usermanuals/en/data/audit.md @@ -38,13 +38,15 @@ $ forgelm audit data/preferences.jsonl --output ./audit/ audit complete — see ./audit/data_audit_report.json ``` -The exit code reflects severity: +Exit codes from `forgelm audit`: | Exit | Meaning | |---|---| -| `0` | Clean. Safe to train. | -| `2` | Warnings. Review the report; training will work but quality may suffer. | -| `3` | Errors. Cross-split leakage or other show-stoppers detected. Fix before training. | +| `0` | Audit completed (regardless of findings — read the report). | +| `1` | IO error (the input path does not exist or cannot be read). | +| `2` | Import error (a required optional extra is missing). | + +`forgelm audit` does not exit non-zero based on the *severity* of what it finds. To gate CI on specific findings, pipe the JSON report through `jq` (see [What's in the report](#whats-in-the-report) below). ## What audit checks @@ -139,19 +141,18 @@ Authoritative source: `forgelm/cli/_parser.py::_add_audit_subcommand`. }, "overall_quality_score": 0.997 }, - "language_distribution": {"tr": 0.992, "en": 0.008}, - "verdict": "warnings" + "language_distribution": {"tr": 0.992, "en": 0.008} } ``` -CI integrations parse `verdict` and individual counts to gate merges. There is no `--strict` flag (see "Removed flags" above) — wrap the JSON envelope with `jq`: +CI integrations parse individual counts to gate merges. There is no `--strict` flag (see "Removed flags" above) and no `verdict` field in the report — wrap the JSON envelope with `jq`: ```yaml # .github/workflows/data.yml - name: Audit data run: | forgelm audit data/train.jsonl --output-format json > audit.json - jq -e '.verdict != "errors" and .pii_summary.severity != "high"' audit.json + jq -e '.cross_split_overlap == 0 and .pii_summary.severity != "high"' audit.json ``` ## Common pitfalls diff --git a/docs/usermanuals/en/data/deduplication.md b/docs/usermanuals/en/data/deduplication.md index 1010b173..e1113292 100644 --- a/docs/usermanuals/en/data/deduplication.md +++ b/docs/usermanuals/en/data/deduplication.md @@ -86,21 +86,20 @@ Both algorithms are streaming — they don't load the whole dataset into memory. ## Removing duplicates -`forgelm audit` *detects* duplicates; it doesn't remove them. Removal is a separate, opt-in step driven by the `audit:` block of your YAML config (so the run is reproducible and audited end-to-end). See the `audit.deduplication` section in [Configuration Reference](#/reference/configuration) for the canonical knobs: - -```yaml -audit: - deduplication: - method: simhash # or 'minhash' - near_dup_threshold: 3 # simhash Hamming distance - jaccard_threshold: 0.85 # MinHash similarity - write_clean_output: data/train.dedup.jsonl - keep_split: train # cross-split tiebreak -``` +`forgelm audit` *detects* duplicates; it does not remove them. There is no `audit:` top-level block in the YAML config (`ForgeConfig` rejects unknown keys), and the `write_clean_output` / `keep_split` fields shown in earlier drafts do not exist. Auto-removal is not implemented. + +To drop duplicates, use the pair-level report that audit writes to disk: -Re-run `forgelm audit data/train.jsonl` with that config to materialise the cleaned JSONL. +```shell +# Get the indices of duplicate rows and filter them out with jq +$ jq '[.near_duplicate_summary.pairs[].row_b] | unique' audit/data_audit_report.json > dup_indices.json +$ jq --slurpfile dups dup_indices.json \ + '[to_entries[] | select(.key as $i | $dups[0] | index($i) | not) | .value]' \ + data/train.jsonl > data/train.dedup.jsonl +$ forgelm audit data/train.dedup.jsonl # verify +``` -When duplicates are within a single split, ForgeLM keeps the first occurrence. Across splits, it keeps the train-side row by default and removes from validation/test (configurable via `keep_split`). +The CLI flags `--dedup-method`, `--near-dup-threshold`, and `--jaccard-threshold` control *detection* sensitivity; removal is always a downstream manual step. ## Common pitfalls diff --git a/docs/usermanuals/en/data/ingestion.md b/docs/usermanuals/en/data/ingestion.md index 527673f2..babb2d20 100644 --- a/docs/usermanuals/en/data/ingestion.md +++ b/docs/usermanuals/en/data/ingestion.md @@ -69,7 +69,7 @@ avoid runtime crashes. ## Output formats -`forgelm ingest` emits raw chunks (`{"text": "..."}` JSONL). There is no `--format` flag in v0.5.5 — the only choice is `--output-format {text,json}` for the **summary report** (chunk count, format breakdown, dropped-row reasons), not for the chunk records themselves, which are always raw `text` JSONL. Operators that want synthetic-prompt or Q&A datasets layer that as a downstream step (see [Synthetic Data](#/data/synthetic-data)) against the raw JSONL this command produces: +`forgelm ingest` emits raw chunks (`{"text": "..."}` JSONL). There is no `--format` flag in v0.7.0 — the only choice is `--output-format {text,json}` for the **summary report** (chunk count, format breakdown, dropped-row reasons), not for the chunk records themselves, which are always raw `text` JSONL. Operators that want synthetic-prompt or Q&A datasets layer that as a downstream step (see [Synthetic Data](#/data/synthetic-data)) against the raw JSONL this command produces: ```json {"text": "Section 4.2: All payment processing must comply with PCI-DSS standards…", "metadata": {"source": "policy.pdf", "chunk": 17}} diff --git a/docs/usermanuals/en/data/language-detection.md b/docs/usermanuals/en/data/language-detection.md index dfef7089..51a15a01 100644 --- a/docs/usermanuals/en/data/language-detection.md +++ b/docs/usermanuals/en/data/language-detection.md @@ -35,16 +35,9 @@ For very short rows (<50 characters), language detection becomes unreliable — ## Configuration -```yaml -audit: - language_detection: - enabled: true - expected: "tr" # explicit expected language - min_chars: 50 # rows shorter than this are 'unknown' - mixed_threshold: 0.3 # if second-language confidence > 30%, mark 'mixed' -``` +> **Note:** There is no `audit:` top-level block in the YAML config (`ForgeConfig` rejects unknown keys). Language detection is automatic and always-on in `forgelm audit`. The `--pii-ml-language` flag is available only for the Presidio ML-NER layer, not for the `langdetect`-based language distribution check itself. -If you don't set `expected`, audit reports the distribution without flagging outliers — useful for genuinely multilingual datasets. +If your dataset is intentionally multilingual, audit reports the distribution without needing any configuration — see the tip in [Common pitfalls](#common-pitfalls) below. ## Per-language Distribution Report diff --git a/docs/usermanuals/en/data/leakage.md b/docs/usermanuals/en/data/leakage.md index c6f9c0f4..ce5a5020 100644 --- a/docs/usermanuals/en/data/leakage.md +++ b/docs/usermanuals/en/data/leakage.md @@ -54,7 +54,7 @@ $ forgelm audit data/ # audits train.jsonl + val.jsonl + test.jsonl Audit refuses to certify these splits. The full pair-level report lives in the on-disk audit JSON. -exit code: 3 +exit code: 0 ``` Inspect the per-row pairs that triggered the failure with `jq`: @@ -69,21 +69,11 @@ $ jq '.cross_split_overlap.pairs[]' audit/data_audit_report.json | head 1. **Re-split the data**, this time grouping at the source level (don't split paraphrases, group documents). Use the `--group-by` flag in your splitter. 2. **Re-extract** if leakage came from duplicate ingestion (the same FAQ ingested twice). -3. **Remove** the leaked rows from the smaller split manually — the audit JSON envelope's `cross_split_overlap.pairs` map names every offending row id under each split-pair entry (e.g. `cross_split_overlap.pairs["train↔val"]`). Pipe through `jq` to strip them out, then re-run `forgelm audit` to confirm the chain re-passes. There is no auto-remove CLI flag in v0.5.5 — adding one is on the roadmap, but until it ships the explicit `jq` step keeps the deletion auditable. +3. **Remove** the leaked rows from the smaller split manually — the audit JSON envelope's `cross_split_overlap.pairs` map names every offending row id under each split-pair entry (e.g. `cross_split_overlap.pairs["train↔val"]`). Pipe through `jq` to strip them out, then re-run `forgelm audit` to confirm the chain re-passes. There is no auto-remove CLI flag in v0.7.0 — the explicit `jq` step keeps the deletion auditable. ## Configuration -```yaml -audit: - leakage_check: - enabled: true - threshold: 0 # zero tolerance — fail audit at any leakage - near_dup_hamming: 3 # match threshold - fields_to_check: ["prompt", "chosen", "response"] - fail_severity: "error" # `error` blocks training, `warn` just logs -``` - -Most teams use the default — zero tolerance. If you have a very large dataset where some leakage is unavoidable, raise `threshold` to a small fraction (e.g. 0.001) but document why. +> **Note:** There is no `audit:` top-level block in the YAML config (`ForgeConfig` rejects unknown keys). Leakage detection is always-on when `forgelm audit` is run on a multi-split dataset. The near-duplicate Hamming threshold is controlled via the `--near-dup-threshold` flag on `forgelm audit` (default 3). ## Why "near-dup" matters here diff --git a/docs/usermanuals/en/data/pii-masking.md b/docs/usermanuals/en/data/pii-masking.md index e7b9c5ac..1448af24 100644 --- a/docs/usermanuals/en/data/pii-masking.md +++ b/docs/usermanuals/en/data/pii-masking.md @@ -96,17 +96,14 @@ language hint, use the audit subcommand: $ forgelm audit ./data/*.jsonl --output ./out/ --pii-ml --pii-ml-language de ``` -Or pin it in YAML: - -```yaml -ingestion: - pii_mask: - enabled: true - locale: "de" - categories: ["email", "phone", "iban", "id_de"] - skip: ["ip"] # don't redact IPs +For a Presidio ML-NER pass with a locale hint, pass `--pii-ml-language` to the CLI: + +```shell +$ forgelm ingest ./corpus/ --pii-mask --output out.jsonl ``` +> **Note:** There is no `ingestion:` top-level block in the YAML config (`ForgeConfig` rejects unknown keys). Locale and category selection for the regex PII layer are available only via the programmatic API — `mask_pii(text, locale="de")` — or via CLI flags such as `--pii-ml-language de` for the Presidio ML-NER pass. + ## Programmatic API For pipelines that need PII detection outside ingest: diff --git a/docs/usermanuals/en/data/pii-ml.md b/docs/usermanuals/en/data/pii-ml.md index e6f9194e..db09c611 100644 --- a/docs/usermanuals/en/data/pii-ml.md +++ b/docs/usermanuals/en/data/pii-ml.md @@ -123,7 +123,7 @@ The function returns an empty dict for non-string input, missing extras, or tran ## What's NOT in this layer - **DATE / TIME / NUMBER detection.** Presidio supports more entity types than the three ForgeLM maps; the others (DATE, NRP, CRYPTO, IP_ADDRESS, …) are not currently mapped because their privacy semantics are different. Open an issue if your compliance flow needs them. -- **PII *masking* via Presidio.** The current adapter is detection-only — for masking, the regex `--pii-mask` flag still owns ingest-side rewriting. Presidio's anonymizer module is a separate dependency and not wired up in v0.5.5. +- **PII *masking* via Presidio.** The current adapter is detection-only — for masking, the regex `--pii-mask` flag still owns ingest-side rewriting. Presidio's anonymizer module is a separate dependency and not wired up in v0.7.0. ## Common pitfalls diff --git a/docs/usermanuals/en/data/quality-filter.md b/docs/usermanuals/en/data/quality-filter.md index d3855e89..b7953d04 100644 --- a/docs/usermanuals/en/data/quality-filter.md +++ b/docs/usermanuals/en/data/quality-filter.md @@ -31,22 +31,12 @@ $ forgelm audit data/ingested.jsonl bullet_only: 3 ``` -Audit *flags* low-quality rows but does not delete them. To drop them, opt in via the `audit.quality_filter.drop_flagged` and `audit.quality_filter.write_clean_output` knobs in your YAML config (see [Configuration Reference](#/reference/configuration)) and re-run audit: - -```yaml -audit: - quality_filter: - enabled: true - drop_flagged: true - write_clean_output: data/clean.jsonl -``` +Audit *flags* low-quality rows but does not delete them. `forgelm audit` only reports; it never drops rows or writes a cleaned JSONL. To remove flagged rows, pipe the audit JSON through `jq` as a downstream manual step and re-run `forgelm audit` to verify the result. + +> **Note:** There is no `audit:` top-level block in the YAML config (`ForgeConfig` rejects unknown keys). The `drop_flagged` and `write_clean_output` fields shown in earlier drafts do not exist; auto-drop-and-write-clean is not implemented. Use `--no-quality-filter` to skip the quality checks entirely. ```shell # v0.6.0+: quality-filter is DEFAULT-ON; the explicit flag is harmless. -# Heuristics populate quality_summary in data_audit_report.json but do -# NOT drop rows or write a cleaned JSONL — that only happens when the -# `audit.quality_filter.drop_flagged: true` + `write_clean_output: PATH` -# YAML keys above are set in a config-driven run. $ forgelm audit data/ingested.jsonl ✓ wrote audit/data_audit_report.json (quality_summary: 45 / 12,400 flagged) @@ -59,26 +49,18 @@ $ forgelm audit data/ingested.jsonl --no-quality-filter ## Tuning thresholds -```yaml -audit: - quality_filter: - enabled: true - min_alpha_ratio: 0.55 # default 0.55 - min_mean_word_length: 3 # default 3 - max_mean_word_length: 10 # default 10 - max_repeated_line_ratio: 0.30 # default 0.30 - min_content_length: 50 # default 50 characters - max_bullet_ratio: 0.90 # default 0.90 -``` +Quality-filter threshold configuration is not exposed as YAML fields in the current release — thresholds are fixed at the heuristic defaults listed below. The CLI flags `--quality-filter` / `--no-quality-filter` control whether the filter runs; there is no per-threshold override flag. -For corpora that legitimately violate one of these (e.g. code-heavy datasets violate alpha ratio), turn off the specific check rather than the whole filter: +| Heuristic | Default | +|---|---| +| `min_alpha_ratio` | 0.55 | +| `min_mean_word_length` | 3 | +| `max_mean_word_length` | 10 | +| `max_repeated_line_ratio` | 0.30 | +| `min_content_length` | 50 characters | +| `max_bullet_ratio` | 0.90 | -```yaml -audit: - quality_filter: - enabled: true - skip: ["min_alpha_ratio"] # code, math, log datasets -``` +For corpora that legitimately violate one of these (e.g. code-heavy datasets violate alpha ratio), use `--no-quality-filter` to skip the filter entirely for that run. ## Conservative-by-default @@ -104,7 +86,7 @@ print(flags) ## Common pitfalls :::warn -**Auto-dropping without review.** Set `--drop-quality-flags` carefully — it removes rows without showing you what got removed. Run `forgelm audit` first to inspect what's flagged. +**Dropping rows without review.** When using `jq` to filter flagged rows from the audit report, pipe carefully — removals are silent. Always run `forgelm audit` on the result to confirm the cleaned dataset passes. ::: :::warn diff --git a/docs/usermanuals/en/deployment/chat.md b/docs/usermanuals/en/deployment/chat.md index 7eb2af91..262228d8 100644 --- a/docs/usermanuals/en/deployment/chat.md +++ b/docs/usermanuals/en/deployment/chat.md @@ -11,7 +11,7 @@ description: Sanity-check your fine-tuned model in a streaming REPL. ```shell $ forgelm chat ./checkpoints/customer-support -ForgeLM 0.5.5 — chat with checkpoints/customer-support +ForgeLM 0.7.0 — chat with checkpoints/customer-support forgelm> how do I cancel my subscription? You can cancel from Settings → Billing → Cancel subscription. Your access continues until the end of the current billing period… @@ -130,7 +130,7 @@ Win rate v2 vs v1: 0.62 (sig p=0.04) ::: :::tip -For automated probing of many prompts, use `forgelm batch-chat --prompts data/probes.jsonl --output responses.jsonl` instead of the interactive REPL. Same model, no manual typing. +For automated probing of many prompts, use `forgelm safety-eval` for batch safety screening, or script a loop that feeds each prompt to `forgelm chat` and collects the output. A dedicated batch-chat subcommand is not available in the current release. ::: ## See also diff --git a/docs/usermanuals/en/deployment/deploy-targets.md b/docs/usermanuals/en/deployment/deploy-targets.md index 1c1264d9..0784ff80 100644 --- a/docs/usermanuals/en/deployment/deploy-targets.md +++ b/docs/usermanuals/en/deployment/deploy-targets.md @@ -28,7 +28,7 @@ $ ollama run my-bot | `tgi` | `tgi-launcher.sh` + Dockerfile | HuggingFace's text-generation-inference. | | `hf-endpoints` | `endpoints-config.json` | One-click deploy to HuggingFace Inference Endpoints. | -KServe and NVIDIA Triton are **not** built-in targets in v0.5.5. The `forgelm deploy --target` parser accepts only the four runtimes above. Operators serving on KServe / Triton author the `InferenceService` manifest or `model_repository/` layout by hand from the GGUF / safetensors artefact. +KServe and NVIDIA Triton are **not** built-in targets. The `forgelm deploy --target` parser accepts only the four runtimes above. Operators serving on KServe / Triton author the `InferenceService` manifest or `model_repository/` layout by hand from the GGUF / safetensors artefact. ## Ollama @@ -47,7 +47,7 @@ PARAMETER temperature 0.7 PARAMETER top_p 0.9 PARAMETER stop "<|im_end|>" -# Generated by ForgeLM 0.5.5 from checkpoint customer-support v1.2.0 +# Generated by ForgeLM from checkpoint customer-support v1.2.0 ``` ForgeLM picks the right `PARAMETER` lines based on the model's tokeniser (chat templates, stop tokens) — no manual configuration needed. @@ -124,18 +124,22 @@ Or paste into HuggingFace's UI for one-click deployment. ## Configuration -```yaml -deployment: - target: "vllm" - served_model_name: "customer-support-v1.2" - max_input_length: 4096 - max_total_tokens: 8192 - gpu_memory_utilization: 0.85 - chat_template: "default" # or path to a .jinja file - system_prompt_default: "You are..." +There is no `deployment:` top-level YAML block — `ForgeConfig` has `extra="forbid"` and rejects unknown keys. Deploy is an explicit CLI subcommand invoked after training, not a YAML-driven automatic step. + +Pass target and output path directly on the command line: + +```shell +$ forgelm deploy ./checkpoints/run \ + --target vllm \ + --output vllm.yaml ``` -When `deployment:` is in your YAML, `forgelm` runs `deploy` automatically as the last step (after eval / safety pass). +Key flags for `forgelm deploy`: + +| Flag | Description | +|---|---| +| `--target ` | One of `ollama`, `vllm`, `tgi`, `hf-endpoints`. | +| `--output ` | File or directory to write the generated config to. | ## What's auto-detected diff --git a/docs/usermanuals/en/evaluation/benchmarks.md b/docs/usermanuals/en/evaluation/benchmarks.md index 17a5c575..fb4b3f77 100644 --- a/docs/usermanuals/en/evaluation/benchmarks.md +++ b/docs/usermanuals/en/evaluation/benchmarks.md @@ -1,11 +1,11 @@ --- title: Benchmark Integration -description: Run lm-evaluation-harness tasks with per-task floor thresholds and auto-revert. +description: Run lm-evaluation-harness tasks with an average accuracy floor and auto-revert. --- # Benchmark Integration -ForgeLM integrates with [lm-evaluation-harness](https://github.com/EleutherAI/lm-evaluation-harness) — the standard benchmark suite for LLMs — and adds the production layer on top: per-task floor thresholds, auto-revert on regression, and structured artifacts that flow into your compliance bundle. +ForgeLM integrates with [lm-evaluation-harness](https://github.com/EleutherAI/lm-evaluation-harness) — the standard benchmark suite for LLMs — and adds the production layer on top: a minimum average accuracy floor, auto-revert on regression, and structured artifacts that flow into your compliance bundle. ## Quick example @@ -14,18 +14,15 @@ evaluation: benchmark: enabled: true tasks: ["hellaswag", "arc_easy", "truthfulqa", "mmlu"] - floors: - hellaswag: 0.55 - arc_easy: 0.70 - truthfulqa: 0.45 - num_fewshot: 0 # zero-shot eval + min_score: 0.55 # average accuracy floor across all tasks + num_fewshot: 0 # zero-shot eval batch_size: 8 output_dir: "./checkpoints/run/artifacts/" ``` -After training, ForgeLM runs the listed tasks, compares to floors, and: -- All tasks pass floor → run succeeds (exit 0) -- Any task drops below floor → auto-revert to last-good checkpoint, exit 3 +After training, ForgeLM runs the listed tasks, computes the mean score, and: +- Mean score meets or exceeds `min_score` → run succeeds (exit 0) +- Mean score falls below `min_score` → auto-revert to last-good checkpoint, exit 3 ## Supported tasks @@ -43,24 +40,21 @@ Anything in `lm-evaluation-harness` works. Common picks: For Turkish projects, ForgeLM ships templates for `mmlu_tr` and `belebele_tr` adapted to Turkish-specific tasks. -## Per-task floors +## Accuracy floor -Floors define the minimum acceptable post-training score per task. The model isn't promoted until *every* task passes its floor. +`min_score` defines the minimum acceptable post-training **mean** score across all listed tasks. The model is only promoted when the average accuracy meets or exceeds this value. ```yaml evaluation: benchmark: - floors: - hellaswag: 0.55 - mmlu: 0.50 - # tasks without floors are reported but don't block promotion - truthfulqa: 0.45 + tasks: ["hellaswag", "mmlu", "truthfulqa"] + min_score: 0.50 # average accuracy floor (0.0–1.0) ``` -A floor of `null` means "report but don't gate". A floor of `0` is the same as no floor (everything passes). +When `min_score` is `null` (the default), benchmarks are run and results are recorded, but the score never blocks promotion. A value of `0.0` is equivalent to no floor. :::tip -Set floors slightly below your pre-training baseline. Goal: catch *regressions*, not require improvement on every task. A model that gains 5% on the target task while losing 2% on hellaswag is usually fine; one that drops 15% on hellaswag is broken. +Set `min_score` slightly below your pre-training average baseline. Goal: catch *regressions*, not require improvement on every task. A model that gains 5% on the target task while losing 2% on hellaswag is usually fine; one whose average drops 15% is broken. ::: ## Pre-train baselines @@ -81,16 +75,13 @@ $ forgelm --config baseline.yaml --benchmark-only "Qwen/Qwen2.5-7B-Instruct" {"hellaswag": 0.61, "arc_easy": 0.75, "truthfulqa": 0.49, "mmlu": 0.52} ``` -A reasonable floor is the baseline minus 0.03 (3% slack for stochastic variation): +A reasonable floor is the baseline average minus 0.03 (3% slack for stochastic variation): ```yaml evaluation: benchmark: - floors: - hellaswag: 0.58 # baseline 0.61 - 0.03 - arc_easy: 0.72 - truthfulqa: 0.46 - mmlu: 0.49 + tasks: ["hellaswag", "arc_easy", "truthfulqa", "mmlu"] + min_score: 0.56 # baseline average ~0.59 - 0.03 ``` ## Output artifacts @@ -129,16 +120,16 @@ CI pipelines parse `verdict`. See [Auto-Revert](#/evaluation/auto-revert) for th |---|---|---|---| | `enabled` | bool | `false` | Master switch. | | `tasks` | list | `[]` | Task names from lm-eval-harness. | -| `floors` | dict | `{}` | Per-task minimum acceptable score. | -| `num_fewshot` | int | `0` | 0 for zero-shot, 5 for 5-shot. | -| `batch_size` | int | `8` | Eval batch size. | +| `min_score` | float | `null` | Minimum average accuracy floor (0.0–1.0). Auto-revert triggers when mean score falls below this. | +| `num_fewshot` | int | `null` | Few-shot example count. `null` uses each task's documented default. | +| `batch_size` | string | `"auto"` | Eval batch size: `"auto"` or an integer string. | | `limit` | int | `null` | Cap rows per task — for fast smoke tests. | -| `device` | string | `"cuda:0"` | Eval device. | +| `output_dir` | string | `null` | Where to save benchmark results JSON. Defaults to the training `output_dir`. | ## Common pitfalls :::warn -**Floors above pre-train baseline.** Set the floor higher than what the base model achieves and *every* run fails — auto-revert kicks in and you never get a checkpoint. Always start with `baseline - margin`. +**`min_score` above pre-train baseline average.** Set `min_score` higher than the base model's mean task score and every run fails — auto-revert kicks in and you never get a checkpoint. Always start with `baseline average - margin`. ::: :::warn @@ -151,6 +142,6 @@ CI pipelines parse `verdict`. See [Auto-Revert](#/evaluation/auto-revert) for th ## See also -- [Auto-Revert](#/evaluation/auto-revert) — what happens when floors fail. +- [Auto-Revert](#/evaluation/auto-revert) — what happens when `min_score` is not met. - [LLM-as-Judge](#/evaluation/judge) — qualitative eval beyond benchmarks. - [Trend Tracking](#/evaluation/trend-tracking) — comparing scores across runs. diff --git a/docs/usermanuals/en/getting-started/first-run.md b/docs/usermanuals/en/getting-started/first-run.md index 186d2311..ef63bd4d 100644 --- a/docs/usermanuals/en/getting-started/first-run.md +++ b/docs/usermanuals/en/getting-started/first-run.md @@ -37,7 +37,7 @@ forgelm doctor — environment check [✓ pass] gpu.inventory 1 GPU(s) — GPU0: NVIDIA RTX 4090 (24.0 GiB). [✓ pass] extras.qlora Installed (module bitsandbytes, purpose: 4-bit / 8-bit QLoRA training). [✓ pass] extras.unsloth Installed (module unsloth, purpose: Unsloth-accelerated training (Linux GPUs only)). - [! warn] extras.deepspeed Optional extra missing — install with: pip install 'forgelm[deepspeed]' (purpose: DeepSpeed ZeRO + offload distributed training). + [! warn] extras.distributed Optional extra missing — install with: pip install 'forgelm[distributed]' (purpose: DeepSpeed ZeRO + offload distributed training). [✓ pass] hf_hub.reachable HuggingFace Hub reachable (HTTP 200). [✓ pass] disk.workspace Workspace /home/me/forgelm — 387.0 GiB free of 500.0 GiB. [! warn] operator.identity FORGELM_OPERATOR not set; audit events will fall back to 'me@workstation'. Pin FORGELM_OPERATOR= for CI / pipeline runs. diff --git a/docs/usermanuals/en/operations/cicd.md b/docs/usermanuals/en/operations/cicd.md index b5e5064b..b2fea42e 100644 --- a/docs/usermanuals/en/operations/cicd.md +++ b/docs/usermanuals/en/operations/cicd.md @@ -13,7 +13,7 @@ ForgeLM is designed to slot cleanly into a CI/CD pipeline step. Every command ha |---|---|---| | `0` | Success | Promote artifacts | | `1` | Configuration error | Fail; fix YAML before retry | -| `2` | Audit warnings | Block merge until reviewed | +| `2` | Training error | Fail; investigate crash / OOM / unhandled exception | | `3` | Auto-revert triggered | Fail; investigate regression | | `4` | Awaiting human approval | Hold pipeline; trigger reviewer notification | diff --git a/docs/usermanuals/en/operations/iso-soc2-deployer.md b/docs/usermanuals/en/operations/iso-soc2-deployer.md index ea5b62e3..e9bc9e42 100644 --- a/docs/usermanuals/en/operations/iso-soc2-deployer.md +++ b/docs/usermanuals/en/operations/iso-soc2-deployer.md @@ -23,7 +23,7 @@ The deep guide answers each with the exact `jq` / CLI command + the artefact it 1. "Show me the audit trail for every model promotion in the past 90 days" → `forgelm verify-audit` + `jq 'select(.event == "human_approval.granted")'`. 2. "Show me the change-control evidence — who approved this model?" → cross-reference `training.started` + `human_approval.granted` events; two distinct operator IDs prove segregation of duties (ISO A.5.3, SOC 2 CC1.5). 3. "Show me the data lineage" → `data_provenance.json`; `sha256` + `hf_revision` pin the corpus. -4. "Show me the supply chain" → `gh release download v0.5.5 --pattern 'sbom-*'`; CycloneDX 1.5 JSON. +4. "Show me the supply chain" → `gh release download v0.7.0 --pattern 'sbom-*'`; CycloneDX 1.5 JSON. 5. "Show me the access controls" → IdP audit log + `FORGELM_OPERATOR` cross-reference. 6. "Show me the encryption posture" → deployer-side substrate (KMS audit log + `data_governance_report.json`). 7. "Show me the incident response" → `audit.classifier_load_failed` + F-compliance-110 strict gate. diff --git a/docs/usermanuals/en/operations/supply-chain.md b/docs/usermanuals/en/operations/supply-chain.md index 374929d4..4d9ac477 100644 --- a/docs/usermanuals/en/operations/supply-chain.md +++ b/docs/usermanuals/en/operations/supply-chain.md @@ -19,7 +19,7 @@ ForgeLM emits a CycloneDX 1.5 SBOM per release tag, and runs `pip-audit` + `band ```bash # All SBOMs for a release. -gh release download v0.5.5 --pattern 'sbom-*' +gh release download v0.7.0 --pattern 'sbom-*' # Pretty-print one. jq . sbom-ubuntu-latest-py3.11.json | less diff --git a/docs/usermanuals/en/reference/configuration.md b/docs/usermanuals/en/reference/configuration.md index f04c4735..21213a64 100644 --- a/docs/usermanuals/en/reference/configuration.md +++ b/docs/usermanuals/en/reference/configuration.md @@ -7,23 +7,28 @@ description: Every YAML field ForgeLM understands, with types, defaults, and not This is the canonical reference for every YAML field ForgeLM accepts. The schema is enforced by Pydantic; running `forgelm --config X.yaml --dry-run` validates your file against it. -The top-level config has 12 blocks: +The top-level config has 15 blocks: ```yaml model: {...} lora: {...} -galore: {...} -datasets: [...] training: {...} +data: {...} +auth: {...} evaluation: {...} -synthetic: {...} -merge: {...} +webhook: {...} distributed: {...} +merge: {...} compliance: {...} -output: {...} -auth: {...} +risk_assessment: {...} +monitoring: {...} +synthetic: {...} +retention: {...} +pipeline: {...} ``` +> **Note:** `galore` fields are flat sub-fields inside `training:` (prefixed `galore_*`), not a separate top-level block. See the [`training:`](#training) section below. + ## `model:` ```yaml @@ -58,22 +63,10 @@ lora: use_rslora: false # rsLoRA scaling ``` -## `galore:` (alternative to `lora:`) +## `data:` ```yaml -galore: - enabled: false # incompatible with lora.r when true - rank: 256 - update_proj_gap: 200 - scale: 0.25 - proj_type: "std" # std | reverse_std | right | left - target_modules: ["attn", "mlp"] -``` - -## `datasets:` - -```yaml -datasets: +data: - path: "data/train.jsonl" # required format: "messages" # auto-detected if omitted weight: 1.0 # mixing weight; sum across all datasets @@ -130,7 +123,7 @@ evaluation: benchmark: enabled: false tasks: [] - floors: {} + min_score: null # scalar float floor across averaged tasks (replaces removed per-task floors dict) num_fewshot: 0 batch_size: 8 limit: null @@ -161,11 +154,7 @@ evaluation: lookback_runs: 10 drift_p_threshold: 0.05 fail_on_concern: "high" - auto_revert: - enabled: false - last_good_checkpoint: null - notify_on_revert: true - keep_failed_checkpoint: true + auto_revert: false # boolean; set true to enable EU AI Act high-risk regression gate guards: {} # custom callable guards ``` @@ -262,30 +251,65 @@ compliance: license: "Apache-2.0" ``` -## `output:` +## `webhook:` ```yaml -output: - dir: "./checkpoints/run" # required - model_card: true - save_format: "safetensors" # safetensors | pytorch - save_strategy: "epoch" # epoch | steps | no - save_steps: 500 - webhook: # see [Webhooks](#/operations/webhooks) - url: null - template: "slack" - events: [] - # cost_tracking: # roadmap — not yet implemented; see GPU Cost Estimation page + risks-and-decisions.md - # enabled: false # NOT honoured by forgelm/config.py (no output.cost_tracking surface) - # rate_per_hour: {} - # currency: "USD" - # alert_threshold_usd: null - # halt_threshold_usd: null - gguf: - enabled: false - quant_levels: ["q4_k_m"] - output_dir: "${output.dir}/gguf/" - manifest: true +webhook: + url: null # Slack / Teams / Discord / custom; prefer url_env + url_env: null # env var carrying the webhook URL + notify_on_start: true + notify_on_success: true + notify_on_failure: true + timeout: 10 # HTTP request timeout in seconds + allow_private_destinations: false # SSRF opt-in for in-cluster endpoints + require_https: false # refuse plaintext http:// URLs when true + tls_ca_bundle: null # custom CA bundle path (corporate MITM) +``` + +## `risk_assessment:` + +```yaml +risk_assessment: + intended_use: "" # Article 9(2)(a): intended purpose (free-text) + foreseeable_misuse: [] # Article 9(2)(b): misuse scenarios list + risk_category: "minimal-risk" # unknown | minimal-risk | limited-risk | high-risk | unacceptable + mitigation_measures: [] # Article 9(2)(c): mitigation steps + vulnerable_groups_considered: false # Article 9(2)(b): impact on vulnerable groups +``` + +## `monitoring:` + +```yaml +monitoring: + enabled: false # Enable Article 12 post-market monitoring + endpoint: "" # Monitoring webhook URL (Prometheus / Datadog / custom) + endpoint_env: null # env var overriding endpoint + metrics_export: "none" # none | prometheus | datadog | custom_webhook + alert_on_drift: true # webhook alert on drift-detector regression + check_interval_hours: 24 # monitoring cadence in hours +``` + +## `retention:` + +```yaml +retention: + audit_log_retention_days: 1825 # 5 years default (Article 5(1)(e)) + staging_ttl_days: 7 # days to retain staging model after forgelm reject + ephemeral_artefact_retention_days: 90 # compliance bundles, audit reports + raw_documents_retention_days: 90 # ingested PDF/DOCX/EPUB/TXT/Markdown + enforce: "log_only" # log_only | warn_on_excess | block_on_excess +``` + +## `pipeline:` + +```yaml +pipeline: + output_dir: "./pipeline_run" # pipeline-level output directory + stages: # ordered list of training stages (min 1) + - name: "sft" + training: { trainer: "sft", epochs: 3 } + - name: "dpo" + training: { trainer: "dpo", epochs: 1 } ``` ## `auth:` @@ -301,7 +325,7 @@ auth: There is no `deployment:` top-level YAML key — `ForgeConfig` rejects unknown keys (`extra="forbid"`), so adding one to your training config raises `ConfigError` at load time. Deployment knobs are exposed as `forgelm deploy` CLI flags instead. The live target choices are `--target {ollama,vllm,tgi,hf-endpoints}`; see the [Deploy targets page](#/deployment/deploy-targets) and the [CLI reference](#/reference/cli) for the full surface. -> **Planned for v0.6.0+:** A YAML-backed `deployment:` section is on the [Phase 14 pipeline-chains roadmap on GitHub](https://github.com/HodeTech/ForgeLM/blob/main/docs/roadmap.md) (deferred from earlier v0.5.x placeholders). Until then, treat any "deployment:" YAML you find in third-party templates as informational; only the `forgelm deploy` flags are authoritative. +> **Not yet scheduled:** A YAML-backed `deployment:` section has been deferred past v0.7.0. Until it ships, treat any "deployment:" YAML you find in third-party templates as informational; only the `forgelm deploy` flags are authoritative. ## See also diff --git a/docs/usermanuals/en/training/distributed.md b/docs/usermanuals/en/training/distributed.md index e3f6f67c..61a7a3f3 100644 --- a/docs/usermanuals/en/training/distributed.md +++ b/docs/usermanuals/en/training/distributed.md @@ -48,10 +48,10 @@ Unsloth is a drop-in optimisation for Llama, Qwen, Mistral, and a few others. It ```yaml model: name_or_path: "Qwen/Qwen2.5-7B-Instruct" - use_unsloth: true # the only flag you need + backend: "unsloth" # the only flag you need training: - trainer: "sft" + trainer_type: "sft" # ... rest of training config unchanged ``` @@ -117,7 +117,7 @@ Whichever backend you use, gradient accumulation lets you target an effective ba ```yaml training: - batch_size: 1 # per-device + per_device_train_batch_size: 1 # per-device gradient_accumulation_steps: 32 # effective batch = 1 × 32 × num_gpus ``` diff --git a/docs/usermanuals/en/training/galore.md b/docs/usermanuals/en/training/galore.md index 446f579b..97d1d2e3 100644 --- a/docs/usermanuals/en/training/galore.md +++ b/docs/usermanuals/en/training/galore.md @@ -26,34 +26,30 @@ model: load_in_4bit: false # GaLore prefers full precision max_length: 4096 -galore: - enabled: true - rank: 256 # higher than LoRA — projection rank - update_proj_gap: 200 # re-project every N steps - scale: 0.25 - proj_type: "std" # std (default), reverse_std, right, left - training: - trainer: "sft" + trainer_type: "sft" learning_rate: 1.0e-5 # full-FT learning rate, not LoRA optimizer: "galore_adamw_8bit" - -output: - dir: "./checkpoints/galore" + galore_enabled: true + galore_rank: 256 # higher than LoRA default (128) — projection rank + galore_update_proj_gap: 200 # re-project every N steps + galore_scale: 0.25 + galore_proj_type: "std" # std (default), reverse_std, right, left + output_dir: "./checkpoints/galore" ``` -Note: when `galore.enabled: true`, ForgeLM automatically uses the GaLore-aware optimiser; `lora` should not be configured at the same time. +Note: when `training.galore_enabled: true`, ForgeLM automatically uses the GaLore-aware optimiser; `lora` should not be configured at the same time. ## Configuration parameters | Parameter | Type | Default | Description | |---|---|---|---| -| `enabled` | bool | `false` | Master switch. | -| `rank` | int | `256` | Gradient projection rank. Higher = closer to full-FT, more memory. | -| `update_proj_gap` | int | `200` | Steps between re-projections. Lower = adapt to changing gradients faster. | -| `scale` | float | `0.25` | Scaling on the projected gradients. | -| `proj_type` | string | `"std"` | Projection direction. `std` is the default; experiment if convergence stalls. | -| `target_modules` | list | `["attn", "mlp"]` | Which modules to project gradients for. | +| `training.galore_enabled` | bool | `false` | Master switch. | +| `training.galore_rank` | int | `128` | Gradient projection rank. Higher = closer to full-FT, more memory. | +| `training.galore_update_proj_gap` | int | `200` | Steps between re-projections. Lower = adapt to changing gradients faster. | +| `training.galore_scale` | float | `0.25` | Scaling on the projected gradients. | +| `training.galore_proj_type` | string | `"std"` | Projection direction. `std` is the default; experiment if convergence stalls. | +| `training.galore_target_modules` | list | `null` | Which modules to project gradients for. | ## Memory comparison @@ -65,7 +61,7 @@ For a 7B model at `max_length: 4096`, batch size 1: | LoRA r=16 | 0.2% | 18 GB | 9 GB (QLoRA) | | **GaLore r=256** | **100%** | **22 GB** | n/a | -So GaLore at r=256 lets you full-fine-tune a 7B model on a single 24 GB GPU — roughly the same VRAM as plain LoRA at full precision. +So GaLore at r=256 (illustrative; the shipped default is r=128) lets you full-fine-tune a 7B model on a single 24 GB GPU — roughly the same VRAM as plain LoRA at full precision. ## Compute @@ -74,7 +70,7 @@ GaLore is ~15-20% slower per step than LoRA because of the projection/re-project ## Common pitfalls :::warn -**Trying to combine GaLore with LoRA.** They're alternatives, not complements. ForgeLM's config schema rejects setting both `lora.r` and `galore.enabled`. +**Trying to combine GaLore with LoRA.** They're alternatives, not complements. ForgeLM's config schema rejects setting both `lora.r` and `training.galore_enabled`. ::: :::warn diff --git a/docs/usermanuals/en/training/long-context.md b/docs/usermanuals/en/training/long-context.md index 244ea1c6..8c7aaebf 100644 --- a/docs/usermanuals/en/training/long-context.md +++ b/docs/usermanuals/en/training/long-context.md @@ -35,20 +35,19 @@ flowchart LR model: name_or_path: "Qwen/Qwen2.5-7B-Instruct" max_length: 32768 - rope_scaling: - type: "linear" - factor: 4.0 # 8K base × 4 = 32K - sliding_window: 4096 # process in 4K windows load_in_4bit: true training: - trainer: "sft" + trainer_type: "sft" packing: true # critical for throughput neftune_noise_alpha: 5.0 # add training-time embedding noise + rope_scaling: + type: "linear" + factor: 4.0 # 8K base × 4 = 32K + sliding_window_attention: 4096 # process in 4K windows -datasets: - - path: "data/long-docs.jsonl" - format: "messages" +data: + dataset_name_or_path: "data/long-docs.jsonl" ``` ## RoPE scaling types @@ -93,9 +92,10 @@ Throughput improves 30-50% on instruction-tuning data where most examples are fa ```yaml training: packing: true - packing_max_length: 32768 # usually = max_length ``` +Set `model.max_length` to control the maximum packed sequence length. + :::warn Packing assumes examples are independent. If you're training on long documents that should preserve full context (book chapters, source code repos), set `packing: false`. ::: diff --git a/docs/usermanuals/en/training/lora.md b/docs/usermanuals/en/training/lora.md index 50947c1d..368ebe6f 100644 --- a/docs/usermanuals/en/training/lora.md +++ b/docs/usermanuals/en/training/lora.md @@ -64,7 +64,7 @@ lora: modules_to_save: [] # extra modules trained at full precision training: - trainer: "sft" + trainer_type: "sft" learning_rate: 2.0e-4 # LoRA tolerates higher LR than full FT ``` diff --git a/docs/usermanuals/tr/compliance/gdpr.md b/docs/usermanuals/tr/compliance/gdpr.md index 57be3f7a..d8f425a3 100644 --- a/docs/usermanuals/tr/compliance/gdpr.md +++ b/docs/usermanuals/tr/compliance/gdpr.md @@ -53,12 +53,9 @@ Bu raporlar Annex IV paketine akar. Regülatör "eğitim setinizde hangi kişise ForgeLM ham kullanıcı verisini saklamaz — sizin kontrol ettiğiniz JSONL artifact'lar üretir. Otomatik saklama uygulanması için: ```yaml -ingestion: - retention: - raw_documents: - ttl_days: 90 # N gün sonra orijinalleri otomatik sil - audit_reports: - ttl_days: 365 +retention: + raw_documents_retention_days: 90 # N gün sonra orijinalleri otomatik sil + ephemeral_artefact_retention_days: 365 ``` (Asıl silme depolama katmanınızın sorumluluğu; ForgeLM sadece amaçlanan TTL'yi audit log'a kaydeder.) @@ -105,26 +102,14 @@ Yüksek-riskli işleme için GDPR Md. 35 DPIA gerektirir. ForgeLM DPIA'nızı ya - Risk sınıflandırması → `compliance.risk_classification`'dan. - Kişisel veri envanteri → `data_audit_report.json`'dan. -- Uygulanan azaltıcılar → `compliance.risk_assessment.mitigations`'dan. -- Kalıntı riskler → `compliance.risk_assessment.residual_risks`'tan. +- Uygulanan azaltıcılar → `risk_assessment.mitigation_measures`'dan. +- Öngörülebilir kötüye kullanım / kalıntı riskler → `risk_assessment.foreseeable_misuse`'dan (serbest-metin listesi; şemada ayrı bir residual_risks alanı mevcut değildir). DPIA çalışması için yukarıdaki girdileri [GitHub'daki QMS risk tedavi planı](https://github.com/HodeTech/ForgeLM/blob/main/docs/qms/risk_treatment_plan-tr.md) ve [Uygulanabilirlik Beyanı](https://github.com/HodeTech/ForgeLM/blob/main/docs/qms/statement_of_applicability-tr.md) ile eşleştirin (toolkit ile gelen GitHub QMS şablonları). Adanmış bir DPIA şablonu yol haritasındadır; şimdilik risk tedavi planı aynı zemini kapsıyor. ## Konfigürasyon referansı -```yaml -compliance: - data_protection: - framework: "GDPR" # GDPR | KVKK | both - lawful_basis: "legitimate-interest" # consent | contract | legal-obligation | ... - purpose: "X için müşteri-destek asistanı" - data_controller: "Acme Corp" - data_subjects: "telekom müşterileri" - retention_basis: "model yaşam döngüsü (~3 yıl) artı audit dönemi" - international_transfers: - enabled: false # eğitim verisi sınır geçiyorsa true - safeguards: "Standart Sözleşme Hükümleri 2021/914" -``` +ForgeLM'in GDPR hukuki meta verisi (hukuki dayanak, veri sorumlusu vb.) için YAML yüzeyi yoktur — bu öznitelikler `forgelm/config.py`'da değil, kuruluşunuzun hukuki belgelerinde ve DPIA'sında yer almalıdır. `ComplianceMetadataConfig` şeması (`compliance:` üst-düzey bloğu) yalnızca şunları kabul eder: `provider_name`, `provider_contact`, `system_name`, `intended_purpose`, `known_limitations`, `system_version` ve `risk_classification`. `compliance.data_protection` alt-bloğu mevcut değildir ve başlangıçta Pydantic tarafından reddedilir (`extra="forbid"`). ## Sık hatalar diff --git a/docs/usermanuals/tr/compliance/human-oversight.md b/docs/usermanuals/tr/compliance/human-oversight.md index b624c0b1..fe9b4530 100644 --- a/docs/usermanuals/tr/compliance/human-oversight.md +++ b/docs/usermanuals/tr/compliance/human-oversight.md @@ -82,8 +82,7 @@ Her onay (veya red) `audit_log.jsonl`'a eklenir: ```json { - "ts": "2026-04-29T15:18:42Z", - "seq": 87, + "timestamp": "2026-04-29T15:18:42Z", "event": "human_approval.granted", "run_id": "abc123", "approver": "ci-reviewer@example", diff --git a/docs/usermanuals/tr/compliance/model-card.md b/docs/usermanuals/tr/compliance/model-card.md index 4acf9b05..5787f48e 100644 --- a/docs/usermanuals/tr/compliance/model-card.md +++ b/docs/usermanuals/tr/compliance/model-card.md @@ -29,7 +29,7 @@ EU AI Act Madde 13 şeffaflığı zorunlu kılar: deploy edilen AI sistemleri ne ```markdown # Acme Customer Support v1.2.0 -ForgeLM 0.5.5 kullanılarak Qwen2.5-7B-Instruct'tan fine-tune edilmiş +ForgeLM 0.7.0 kullanılarak Qwen2.5-7B-Instruct'tan fine-tune edilmiş müşteri-destek asistanı. ## Model detayları @@ -113,27 +113,14 @@ Bu modeli kullanırsanız lütfen şöyle atıf yapın: title = {Acme Customer Support v1.2.0}, author = {Acme Corp}, year = {2026}, - note = {ForgeLM 0.5.5 ile fine-tune edildi} + note = {ForgeLM 0.7.0 ile fine-tune edildi} } ``` ``` ## Konfigürasyon -```yaml -output: - model_card: true # varsayılan - model_card_template: null # özel Jinja2 template yolu -``` - -Marka için varsayılan template'i override edin: - -```yaml -output: - model_card_template: "templates/acme-card.j2" -``` - -Template aynı veriyi alır — sadece farklı render eder. +Model card üretimi her başarılı koşudan sonra otomatiktir — etkinleştirmek veya devre dışı bırakmak için YAML anahtarı yoktur. ForgeLM'de `output:` üst-düzey config bloğu bulunmaz; böyle bir blok eklenirse Pydantic doğrulaması tarafından reddedilir (`extra="forbid"`). Template'i özelleştirmeniz gerekiyorsa, belgelemeden önce gerçek alan adı için `forgelm/config.py`'daki güncel şemayı kontrol edin. ## Manuel eklemeler @@ -157,4 +144,4 @@ HuggingFace Hub yayını için ForgeLM'in model card'ı HuggingFace'in standart - [Annex IV](#/compliance/annex-iv) — Madde 11 kardeşi. - [Uyumluluk Genel Bakış](#/compliance/overview) — bağlam. -- [Konfigürasyon Referansı](#/reference/configuration) — `output.model_card` alanı. +- [Konfigürasyon Referansı](#/reference/configuration) — model card girdileri olarak kullanılan `compliance.*` alanları. diff --git a/docs/usermanuals/tr/compliance/verify-audit.md b/docs/usermanuals/tr/compliance/verify-audit.md index 8890cca9..a018863f 100644 --- a/docs/usermanuals/tr/compliance/verify-audit.md +++ b/docs/usermanuals/tr/compliance/verify-audit.md @@ -40,7 +40,7 @@ sequenceDiagram ## Hızlı başlangıç ```shell -$ forgelm verify-audit checkpoints/run/compliance/audit_log.jsonl +$ forgelm verify-audit checkpoints/run/audit_log.jsonl OK: 87 entries verified ``` @@ -48,7 +48,7 @@ HMAC ile yetkilendirilmiş log'lar için önce operatör sırrını set edin: ```shell $ FORGELM_AUDIT_SECRET="$(cat /run/secrets/audit-secret)" \ - forgelm verify-audit checkpoints/run/compliance/audit_log.jsonl + forgelm verify-audit checkpoints/run/audit_log.jsonl OK: 87 entries verified (HMAC validated) ``` @@ -61,7 +61,7 @@ Her kaydın HMAC ile yetkilendirilmiş olması gerektiğinde (kurumsal denetim p ```shell $ FORGELM_AUDIT_SECRET="$(cat /run/secrets/audit-secret)" \ forgelm verify-audit --require-hmac \ - checkpoints/run/compliance/audit_log.jsonl + checkpoints/run/audit_log.jsonl ``` Sıkı mod iki güvenlik ağını birden devreye sokar: @@ -92,7 +92,7 @@ FAIL at line 53: prev_hash mismatch — chain break suggests entry was inserted, Satır numarası olmayan çıplak bir neden, hatanın zincir yürüyüşünden önce meydana geldiğini gösterir (örn. eksik genesis manifest, satır 1'de JSON çözüm hatası): ```text -FAIL: manifest present but unreadable at 'checkpoints/run/compliance/audit_log.jsonl.manifest.json': … +FAIL: manifest present but unreadable at 'checkpoints/run/audit_log.jsonl.manifest.json': … ``` Her iki durumda da çıkış kodu `1`'dir. Log'u kanıt saymadan önce inceleyin. @@ -127,4 +127,5 @@ Her iki durumda da çıkış kodu `1`'dir. Log'u kanıt saymadan önce inceleyin - [Audit Log](#/compliance/audit-log) — bu komutun doğruladığı log'a dair operatör-odaklı kılavuz. - [Annex IV](#/compliance/annex-iv) — doğrulayıcısı (`forgelm verify-annex-iv`) bu komutun tasarım desenini paylaşan teknik dokümantasyon artifact'ı. - [GGUF Doğrulama](#/deployment/verify-gguf) — deployment-bütünlük yüzeyindeki kardeş doğrulayıcı. +- [Model Bütünlüğünü Doğrulama](#/compliance/verify-integrity) — Article 15 model-bütünlük manifestinin kardeş doğrulayıcısı. - [`audit_event_catalog-tr.md`](https://github.com/HodeTech/ForgeLM/blob/main/docs/reference/audit_event_catalog-tr.md) — doğrulanan log'un *içinde* görünen event'ler (GitHub kaynağı). diff --git a/docs/usermanuals/tr/compliance/verify-integrity.md b/docs/usermanuals/tr/compliance/verify-integrity.md new file mode 100644 index 00000000..642ee1c9 --- /dev/null +++ b/docs/usermanuals/tr/compliance/verify-integrity.md @@ -0,0 +1,114 @@ +--- +title: Model Bütünlüğünü Doğrula +description: Eğitilmiş bir model dizinini SHA-256 bütünlük manifest'ine (model_integrity.json) karşı yeniden hash'leyerek eğitimden bu yana hiçbir artefaktın değişmediğini, kaldırılmadığını veya eklenmediğini kanıtlayın. +--- + +# Model Bütünlüğünü Doğrula + +`forgelm verify-integrity`, Madde 15 model-bütünlük manifest'iyle eşleşen salt-okunur doğrulayıcıdır. Compliance export, eğitim sırasında final modelin yanına `model_integrity.json` yazar ve her artefaktın SHA-256'sını ve byte boyutunu kaydeder. `verify-integrity` dizini yeniden gezer, her hash'i yeniden hesaplar ve manifest oluşturulduğundan beri **değişen**, **kaldırılan** veya **eklenen** her dosyayı raporlar. Bu komut, audit *log*'unu doğrulayan [`verify-audit`](#/compliance/verify-audit)'in model *ağırlıkları* karşılığıdır. + +## Ne zaman kullanılır + +- **Eğitilmiş bir modeli deploy etmeden veya göndermeden önce.** Temiz bir `verify-integrity` çıkışı, sunmak üzere olduğunuz byte'ların eğittiğiniz ve kaydettiğiniz byte'lar olduğunu kanıtlar. +- **Modeli makineler veya depolama katmanları arasında taşıdıktan sonra.** Aktarım sırasındaki sessiz bozulma, değişen/kaldırılan artefakt olarak ortaya çıkar. +- **CI/CD release kapılarında.** Compliance export'tan sonra çalıştırın; sıfır-dışı çıkışta release'i başarısız kılın. +- **Periyodik bir uyumluluk taramasının parçası olarak.** Arşivlenen modellerin zamanlanmış yeniden-doğrulaması, tahrifatı veya bit-rot'u erken yakalar. + +## Nasıl çalışır + +```mermaid +sequenceDiagram + participant CI as CI / operatör + participant Verify as forgelm verify-integrity + participant Manifest as model_integrity.json + participant Dir as model dizini + + CI->>Verify: verify-integrity MODEL_DIR + Verify->>Manifest: kayıtlı {file, sha256, size_bytes} yükle + Verify->>Dir: artefaktları gez (manifest dosyasının kendisi hariç) + loop her artefakt için + Verify->>Verify: sha256 yeniden hesapla, manifest ile karşılaştır + end + Verify->>Verify: changed / removed / added sınıflandır + Verify-->>CI: çıkış 0 (hepsi eşleşti) / 1 (uyuşmazlık veya girdi hatası) / 2 (runtime I/O hatası) +``` + +## Hızlı başlangıç + +```shell +$ forgelm verify-integrity ./checkpoints/final_model +OK: all 12 recorded artifact(s) present and unchanged. +``` + +CI için makine-okunur çıktı: + +```shell +$ forgelm verify-integrity ./checkpoints/final_model --output-format json +``` + +```json +{ + "success": true, + "valid": true, + "reason": "All 12 recorded artifact(s) present and unchanged.", + "changed": [], + "removed": [], + "added": [], + "verified_count": 12, + "path": "/work/checkpoints/final_model" +} +``` + +## Ayrıntılı kullanım + +### Bir uyuşmazlığı okumak + +Bir artefakt artık manifest ile eşleşmediğinde, diff listeleri dolar ve komut `1` ile çıkar: + +```json +{ + "success": false, + "valid": false, + "reason": "Model artifacts do not match model_integrity.json: 1 changed, 1 removed.", + "changed": ["adapter_model.safetensors"], + "removed": ["tokenizer.model"], + "added": [], + "verified_count": 10, + "path": "/work/checkpoints/final_model" +} +``` + +- `changed` — SHA-256'sı artık manifest ile eşleşmeyen artefaktlar. +- `removed` — manifest'te kayıtlı ama diskte olmayan artefaktlar. +- `added` — diskte olup manifest'te kayıtlı olmayan dosyalar (manifest dosyasının kendisi yürüyüşten her zaman hariç tutulur). + +### Çıkış kodu özeti + +| Kod | Anlamı | +|---|---| +| `0` | Her kayıtlı artefakt mevcut ve değişmemiş, fazladan dosya yok. | +| `1` | Bütünlük uyuşmazlığı (changed / removed / added dosya) **veya** operatör / girdi hatası — eksik yol, yolun dizin yerine dosya olması, manifest bulunamadı, malformed JSON, list olmayan `artifacts` ya da model dizininden kaçan bir manifest girdi yolu. | +| `2` | Erişilebilir bir yolda gerçek runtime I/O hatası (okuma hatası, yürüyüş sırasında izin reddi). | + +Runtime-hatası zarfı (çıkış `2`) yalnızca `{"success": false, "error": "…"}` döndürür — önce `success` üzerinden dallanın, ardından `valid` ve diff listelerini inceleyin. + +## Sık yapılan hatalar + +:::warn +**Eksik bir `model_integrity.json`'ı zararsız saymak.** Manifest olmadan karşılaştırılacak bir şey yoktur — `verify-integrity` `0` değil `1` ile çıkar. Bu kapıya güvenmeden önce compliance export'un manifest'i yazdığını doğrulayın. +::: + +:::warn +**Yeniden-quantization veya yeniden-export sonrası doğrulamak.** Bir GGUF veya merge edilmiş varyant üretmek byte'ları değiştirir; o modelin kendi taze üretilmiş manifest'ine ihtiyacı vardır. Dönüştürülmüş bir artefaktı orijinal eğitim manifest'ine karşı doğrulamayın. +::: + +:::tip +**Herhangi bir deploy adımından önce doğrulayıcıyı CI'da sabitleyin.** Compliance export'tan sonra `forgelm verify-integrity --output-format json`'ı sıkı bir kapı olarak bağlayın. Sıfır-dışı çıkış release pipeline'ını başarısız kılmalıdır. +::: + +## Ayrıca bakın + +- [Audit Zincirini Doğrula](#/compliance/verify-audit) — Madde 12 audit *log*'u için eşlenik doğrulayıcı (bu komut model *ağırlıklarını* kapsar). +- [Annex IV](#/compliance/annex-iv) — bütünlük manifest'iyle birlikte export edilen teknik-dokümantasyon artefaktı. +- [Verify GGUF](#/deployment/verify-gguf) — export edilmiş bir GGUF model dosyası için bütünlük doğrulayıcısı. +- [`verify_integrity_subcommand-tr.md`](https://github.com/HodeTech/ForgeLM/blob/main/docs/reference/verify_integrity_subcommand-tr.md) — tam bayrak-seviyesi referans (GitHub kaynağı). diff --git a/docs/usermanuals/tr/concepts/data-formats.md b/docs/usermanuals/tr/concepts/data-formats.md index c016fd41..d183b08e 100644 --- a/docs/usermanuals/tr/concepts/data-formats.md +++ b/docs/usermanuals/tr/concepts/data-formats.md @@ -75,12 +75,12 @@ Tek yanıt + thumbs-up/down. Eşli tercihten daha kolay toplanır. ```json { "prompt": "Aboneliği nasıl iptal ederim?", - "response": "Sadece ödemeyi durdur.", + "completion": "Sadece ödemeyi durdur.", "label": false } { "prompt": "Aboneliği nasıl iptal ederim?", - "response": "Ayarlar → Faturalandırma → Aboneliği iptal et…", + "completion": "Ayarlar → Faturalandırma → Aboneliği iptal et…", "label": true } ``` diff --git a/docs/usermanuals/tr/data/audit.md b/docs/usermanuals/tr/data/audit.md index d3cd9501..d6748b82 100644 --- a/docs/usermanuals/tr/data/audit.md +++ b/docs/usermanuals/tr/data/audit.md @@ -38,13 +38,15 @@ $ forgelm audit data/preferences.jsonl --output ./audit/ audit tamamlandı — bkz. ./audit/data_audit_report.json ``` -Exit kodu ciddiyeti yansıtır: +`forgelm audit` exit kodları: | Exit | Anlam | |---|---| -| `0` | Temiz. Eğitim güvenli. | -| `2` | Uyarı. Raporu inceleyin; eğitim çalışır ama kalite düşebilir. | -| `3` | Hata. Split-arası sızıntı veya başka kritik sorun. Düzelt. | +| `0` | Audit tamamlandı (bulgulardan bağımsız — raporu okuyun). | +| `1` | IO hatası (giriş yolu mevcut değil veya okunamıyor). | +| `2` | Import hatası (gerekli bir opsiyonel extra eksik). | + +`forgelm audit`, bulguların *ciddiyetine* göre sıfır dışı exit vermez. CI'da belirli bulgulara göre kapı koymak için JSON raporunu `jq` ile süzün (aşağıdaki [Rapor içeriği](#rapor-içeriği) bölümüne bakın). ## Audit'in kontrol ettikleri @@ -134,18 +136,17 @@ Yetkili kaynak: `forgelm/cli/_parser.py::_add_audit_subcommand`. }, "overall_quality_score": 0.997 }, - "language_distribution": {"tr": 0.992, "en": 0.008}, - "verdict": "warnings" + "language_distribution": {"tr": 0.992, "en": 0.008} } ``` -CI entegrasyonları `verdict` ve sayıları parse ederek merge'i kontrol eder. `--strict` flag'i yoktur (yukarıdaki "Kaldırılan flag'lar"a bakın) — JSON zarfını `jq` ile sarın: +CI entegrasyonları bireysel sayıları parse ederek merge'i kontrol eder. `--strict` flag'i yoktur (yukarıdaki "Kaldırılan flag'lar"a bakın) ve raporda `verdict` alanı bulunmaz — JSON zarfını `jq` ile sarın: ```yaml - name: Audit data run: | forgelm audit data/train.jsonl --output-format json > audit.json - jq -e '.verdict != "errors" and .pii_summary.severity != "high"' audit.json + jq -e '.cross_split_overlap == 0 and .pii_summary.severity != "high"' audit.json ``` ## Sık hatalar diff --git a/docs/usermanuals/tr/data/deduplication.md b/docs/usermanuals/tr/data/deduplication.md index e9d3345a..07691b2a 100644 --- a/docs/usermanuals/tr/data/deduplication.md +++ b/docs/usermanuals/tr/data/deduplication.md @@ -86,21 +86,20 @@ Permutasyon sayısı ve LSH banding bugün kullanıcı tarafından ayarlanabilir ## Tekrarları kaldırma -`forgelm audit` tekrarları *tespit eder*; kaldırmaz. Kaldırma, YAML konfigürasyonunuzun `audit:` bloğundan sürülen ayrı, opt-in bir adımdır (böylece koşu uçtan uca tekrarlanabilir ve audit edilebilir). Kanonik knob'lar için [Configuration Referansı](#/reference/configuration)'ndaki `audit.deduplication` bölümüne bakın: - -```yaml -audit: - deduplication: - method: simhash # veya 'minhash' - near_dup_threshold: 3 # simhash Hamming mesafesi - jaccard_threshold: 0.85 # MinHash benzerliği - write_clean_output: data/train.dedup.jsonl - keep_split: train # split-arası tiebreak -``` +`forgelm audit` tekrarları *tespit eder*; kaldırmaz. YAML konfigürasyonunda `audit:` üst düzey bloğu yoktur (`ForgeConfig` bilinmeyen anahtarları reddeder) ve eski taslakta gösterilen `write_clean_output` / `keep_split` alanları mevcut değildir. Otomatik kaldırma uygulanmamıştır. + +Tekrarları düşürmek için audit'in diske yazdığı çift seviyesindeki raporu kullanın: -Bu config ile `forgelm audit data/train.jsonl`'i tekrar koşturarak temizlenmiş JSONL'i materialise edin. +```shell +# Tekrar satır indislerini alın ve jq ile filtreleyin +$ jq '[.near_duplicate_summary.pairs[].row_b] | unique' audit/data_audit_report.json > dup_indices.json +$ jq --slurpfile dups dup_indices.json \ + '[to_entries[] | select(.key as $i | $dups[0] | index($i) | not) | .value]' \ + data/train.jsonl > data/train.dedup.jsonl +$ forgelm audit data/train.dedup.jsonl # doğrula +``` -Tekrarlar tek split içindeyken ForgeLM ilk tekrarı tutar. Split arasında varsayılan train tarafını tutar ve validation/test'ten kaldırır (`keep_split` ile konfigüre edilebilir). +`--dedup-method`, `--near-dup-threshold` ve `--jaccard-threshold` CLI bayrakları *tespit* hassasiyetini kontrol eder; kaldırma her zaman downstream manuel bir adımdır. ## Sık hatalar diff --git a/docs/usermanuals/tr/data/ingestion.md b/docs/usermanuals/tr/data/ingestion.md index f7a15d1b..caa97460 100644 --- a/docs/usermanuals/tr/data/ingestion.md +++ b/docs/usermanuals/tr/data/ingestion.md @@ -69,7 +69,7 @@ CLI yüzeyinden gizlidir. ## Çıktı formatı -`forgelm ingest` ham chunk'ları emit eder (`{"text": "..."}` JSONL). v0.5.5'te `--format` flag'i yoktur — tek seçenek **özet raporu** (chunk sayısı, format dağılımı, atılan-satır sebepleri) için `--output-format {text,json}`'dur, chunk kayıtlarının kendileri için değil — onlar her zaman ham `text` JSONL olarak yazılır. Sentetik-prompt veya Q&A datasetleri isteyen operatörler bu adımı bu komutun ürettiği ham JSONL üzerinden downstream bir adım olarak katmanlar (bkz. [Sentetik Veri](#/data/synthetic-data)): +`forgelm ingest` ham chunk'ları emit eder (`{"text": "..."}` JSONL). v0.7.0'da `--format` flag'i yoktur — tek seçenek **özet raporu** (chunk sayısı, format dağılımı, atılan-satır sebepleri) için `--output-format {text,json}`'dur, chunk kayıtlarının kendileri için değil — onlar her zaman ham `text` JSONL olarak yazılır. Sentetik-prompt veya Q&A datasetleri isteyen operatörler bu adımı bu komutun ürettiği ham JSONL üzerinden downstream bir adım olarak katmanlar (bkz. [Sentetik Veri](#/data/synthetic-data)): ```json {"text": "Bölüm 4.2: Tüm ödeme işlemleri PCI-DSS standartlarına uymalıdır...", "metadata": {"source": "policy.pdf", "chunk": 17}} diff --git a/docs/usermanuals/tr/data/language-detection.md b/docs/usermanuals/tr/data/language-detection.md index 57362f54..9f6b62ad 100644 --- a/docs/usermanuals/tr/data/language-detection.md +++ b/docs/usermanuals/tr/data/language-detection.md @@ -35,16 +35,9 @@ $ jq '.language_outliers[:3]' audit/data_audit_report.json ## Konfigürasyon -```yaml -audit: - language_detection: - enabled: true - expected: "tr" # açık beklenen dil - min_chars: 50 # bundan kısa satırlar 'unknown' - mixed_threshold: 0.3 # ikinci-dil güveni > %30 ise 'mixed' işaretle -``` +> **Not:** YAML konfigürasyonunda `audit:` üst düzey bloğu yoktur (`ForgeConfig` bilinmeyen anahtarları reddeder). Dil tespiti `forgelm audit`'te otomatik ve her zaman aktiftir. `--pii-ml-language` bayrağı yalnızca Presidio ML-NER katmanı için geçerlidir; `langdetect` tabanlı dil dağılım kontrolü için değil. -`expected` ayarlamazsanız audit dağılımı aykırı flag'lemeden raporlar — gerçekten çok dilli dataset'ler için faydalı. +Dataset'iniz bilinçli olarak çok dilli ise audit herhangi bir konfigürasyona gerek kalmadan dağılımı raporlar — aşağıdaki [Sık hatalar](#sık-hatalar) bölümündeki ipucuna bakın. ## Dil dağılım raporu diff --git a/docs/usermanuals/tr/data/leakage.md b/docs/usermanuals/tr/data/leakage.md index 0aa69e16..b21e23b1 100644 --- a/docs/usermanuals/tr/data/leakage.md +++ b/docs/usermanuals/tr/data/leakage.md @@ -54,7 +54,7 @@ $ forgelm audit data/ # train.jsonl + val.jsonl + test.jsonl'ı denetler Audit bu split'leri onaylamayı reddeder. Çift seviyesinde tam rapor disk üzerindeki audit JSON'da. -exit kodu: 3 +exit kodu: 0 ``` Hatayı tetikleyen satır seviyesindeki çiftleri `jq` ile inceleyin: @@ -69,21 +69,11 @@ $ jq '.cross_split_overlap.pairs[]' audit/data_audit_report.json | head 1. **Veriyi yeniden bölün**, bu sefer kaynak seviyesinde gruplayarak (parafraz'ları bölmeyin, dokümanları gruplayın). Splitter'ınızda `--group-by` bayrağı kullanın. 2. **Yeniden çıkarma** sızıntı tekrar ingest'ten geliyorsa (aynı FAQ iki kez ingest edilmiş). -3. **Kaldırma** küçük split'ten sızdıran satırları manuel olarak — audit JSON zarfının `cross_split_overlap.pairs` haritası her ihlal eden satır id'sini split-çifti girdisi başına adlandırır (ör. `cross_split_overlap.pairs["train↔val"]`). `jq` ile süzüp çıkarın, sonra `forgelm audit`'i yeniden koşturarak zincirin temiz geçtiğini doğrulayın. v0.5.5'te otomatik kaldırma CLI bayrağı yoktur — yol haritasında bulunsa da gelene kadar açık `jq` adımı silmeyi denetlenebilir tutar. +3. **Kaldırma** küçük split'ten sızdıran satırları manuel olarak — audit JSON zarfının `cross_split_overlap.pairs` haritası her ihlal eden satır id'sini split-çifti girdisi başına adlandırır (ör. `cross_split_overlap.pairs["train↔val"]`). `jq` ile süzüp çıkarın, sonra `forgelm audit`'i yeniden koşturarak zincirin temiz geçtiğini doğrulayın. v0.7.0'da otomatik kaldırma CLI bayrağı yoktur — açık `jq` adımı silmeyi denetlenebilir tutar. ## Konfigürasyon -```yaml -audit: - leakage_check: - enabled: true - threshold: 0 # sıfır tolerans — herhangi sızıntıda audit fail - near_dup_hamming: 3 # eşleşme eşiği - fields_to_check: ["prompt", "chosen", "response"] - fail_severity: "error" # `error` eğitimi engeller, `warn` sadece loglar -``` - -Çoğu ekip varsayılanı kullanır — sıfır tolerans. Bir miktar sızıntının kaçınılmaz olduğu çok büyük dataset'iniz varsa `threshold`'ı küçük bir orana yükseltin (ör. 0.001) ama nedenini belgeleyin. +> **Not:** YAML konfigürasyonunda `audit:` üst düzey bloğu yoktur (`ForgeConfig` bilinmeyen anahtarları reddeder). Sızıntı tespiti, `forgelm audit` çok-split dataset üzerinde koşturulduğunda her zaman aktiftir. Near-duplicate Hamming eşiği `forgelm audit`'deki `--near-dup-threshold` bayrağıyla kontrol edilir (varsayılan 3). ## "Near-dup" neden önemli diff --git a/docs/usermanuals/tr/data/pii-masking.md b/docs/usermanuals/tr/data/pii-masking.md index af6e95f3..a15727a4 100644 --- a/docs/usermanuals/tr/data/pii-masking.md +++ b/docs/usermanuals/tr/data/pii-masking.md @@ -96,17 +96,14 @@ Presidio ML-NER pass için audit subcommand'ını kullanın: $ forgelm audit ./data/*.jsonl --output ./out/ --pii-ml --pii-ml-language de ``` -Veya YAML'da pin'leyin: - -```yaml -ingestion: - pii_mask: - enabled: true - locale: "de" - categories: ["email", "phone", "iban", "id_de"] - skip: ["ip"] # IP'leri redakte etme +Presidio ML-NER geçişi için locale ipucu vermek üzere CLI bayrağını kullanın: + +```shell +$ forgelm ingest ./corpus/ --pii-mask --output out.jsonl ``` +> **Not:** YAML konfigürasyonunda `ingestion:` üst düzey bloğu yoktur (`ForgeConfig` bilinmeyen anahtarları reddeder). Regex PII katmanı için locale ve kategori seçimi yalnızca programatik API üzerinden — `mask_pii(text, locale="de")` — ya da Presidio ML-NER geçişi için `--pii-ml-language de` gibi CLI bayrakları aracılığıyla mevcuttur. + ## Programatik API Ingest dışı PII tespiti gerektiren pipeline'lar için: diff --git a/docs/usermanuals/tr/data/pii-ml.md b/docs/usermanuals/tr/data/pii-ml.md index 2f08ad39..556d7cdc 100644 --- a/docs/usermanuals/tr/data/pii-ml.md +++ b/docs/usermanuals/tr/data/pii-ml.md @@ -123,7 +123,7 @@ Fonksiyon non-string input, eksik extra'lar veya geçici analyzer hataları içi ## Bu katmanda OLMAYAN şeyler - **DATE / TIME / NUMBER tespiti.** Presidio ForgeLM'in haritaladığı üç entity tipinden fazlasını destekler; diğerleri (DATE, NRP, CRYPTO, IP_ADDRESS, …) şu anda haritalı değil çünkü gizlilik semantikleri farklı. Compliance akışınız bunlara ihtiyaç duyuyorsa bir issue açın. -- **Presidio üzerinden PII *maskeleme*.** Mevcut adaptör tespit-only — maskeleme için regex `--pii-mask` flag'i hâlâ ingest tarafı yeniden yazımına sahiptir. Presidio'nun anonymizer modülü ayrı bir bağımlılıktır ve v0.5.5'da bağlı değildir. +- **Presidio üzerinden PII *maskeleme*.** Mevcut adaptör tespit-only — maskeleme için regex `--pii-mask` flag'i hâlâ ingest tarafı yeniden yazımına sahiptir. Presidio'nun anonymizer modülü ayrı bir bağımlılıktır ve v0.7.0'da bağlı değildir. ## Yaygın tuzaklar diff --git a/docs/usermanuals/tr/data/quality-filter.md b/docs/usermanuals/tr/data/quality-filter.md index 75f2406b..6270f66d 100644 --- a/docs/usermanuals/tr/data/quality-filter.md +++ b/docs/usermanuals/tr/data/quality-filter.md @@ -31,54 +31,36 @@ $ forgelm audit data/ingested.jsonl bullet_only: 3 ``` -Audit, düşük kaliteli satırları *flagler* ama silmez. Düşürmek için, YAML konfigürasyonunuzdaki `audit.quality_filter.drop_flagged` ve `audit.quality_filter.write_clean_output` knob'larıyla opt-in olun ([Configuration Referansı](#/reference/configuration)) ve audit'i tekrar koşturun: - -```yaml -audit: - quality_filter: - enabled: true - drop_flagged: true - write_clean_output: data/clean.jsonl -``` +Audit, düşük kaliteli satırları *flagler* ama silmez. `forgelm audit` yalnızca raporlar; satır düşürmez veya temizlenmiş JSONL yazmaz. Flaglenen satırları kaldırmak için audit JSON'ını `jq` ile bir downstream manuel adım olarak süzün ve sonucu doğrulamak için `forgelm audit`'i yeniden koşturun. + +> **Not:** YAML konfigürasyonunda `audit:` üst düzey bloğu yoktur (`ForgeConfig` bilinmeyen anahtarları reddeder). Eski taslakta gösterilen `drop_flagged` ve `write_clean_output` alanları mevcut değildir; otomatik-düşür-ve-temiz-yaz uygulanmamıştır. Kalite kontrollerini tamamen atlamak için `--no-quality-filter` kullanın. ```shell -# v0.6.0+: quality-filter is DEFAULT-ON; the explicit flag is harmless. -# Heuristics populate quality_summary in data_audit_report.json but do -# NOT drop rows or write a cleaned JSONL — that only happens when the -# `audit.quality_filter.drop_flagged: true` + `write_clean_output: PATH` -# YAML keys above are set in a config-driven run. +# v0.6.0+: quality-filter varsayılan AÇIK; explicit flag zararsız. $ forgelm audit data/ingested.jsonl ✓ wrote audit/data_audit_report.json (quality_summary: 45 / 12,400 flagged) -# Pre-v0.6.0 (or to be explicit), pass the flag: +# Pre-v0.6.0 (veya açık olmak için) flag geçin: $ forgelm audit data/ingested.jsonl --quality-filter -# Opt out of the new default if your CI gates depend on opt-in semantics: +# CI gate'leriniz opt-in semantiğine bağlıysa yeni varsayılandan çıkın: $ forgelm audit data/ingested.jsonl --no-quality-filter ``` ## Eşik ayarlama -```yaml -audit: - quality_filter: - enabled: true - min_alpha_ratio: 0.55 # varsayılan 0.55 - min_mean_word_length: 3 # varsayılan 3 - max_mean_word_length: 10 # varsayılan 10 - max_repeated_line_ratio: 0.30 # varsayılan 0.30 - min_content_length: 50 # varsayılan 50 karakter - max_bullet_ratio: 0.90 # varsayılan 0.90 -``` +Kalite filtresi eşik konfigürasyonu mevcut sürümde YAML alanı olarak açık değildir — eşikler aşağıda listelenen heuristik varsayılanlarına sabit. `--quality-filter` / `--no-quality-filter` CLI bayrakları filtrenin çalışıp çalışmayacağını kontrol eder; eşik başına override bayrağı yoktur. -Birini meşru ihlal eden corpus'lar (ör. kod-ağırlıklı dataset'ler alfa oranını ihlal eder) için filtre tamamı yerine spesifik kontrolü kapatın: +| Heuristik | Varsayılan | +|---|---| +| `min_alpha_ratio` | 0.55 | +| `min_mean_word_length` | 3 | +| `max_mean_word_length` | 10 | +| `max_repeated_line_ratio` | 0.30 | +| `min_content_length` | 50 karakter | +| `max_bullet_ratio` | 0.90 | -```yaml -audit: - quality_filter: - enabled: true - skip: ["min_alpha_ratio"] # kod, matematik, log dataset'leri -``` +Bunlardan birini meşru ihlal eden corpus'lar için (ör. kod-ağırlıklı dataset'ler alfa oranını ihlal eder) `--no-quality-filter` ile o koşu için filtreyi tamamen atlayın. ## Tasarım gereği muhafazakar @@ -104,7 +86,7 @@ print(flags) ## Sık hatalar :::warn -**İncelemeden otomatik düşürme.** `--drop-quality-flags`'i dikkatli ayarlayın — neyin kaldırıldığını size göstermeden satırları kaldırır. Önce neyin flaglendiğini incelemek için `forgelm audit` koşturun. +**İncelemeden satır kaldırma.** Audit raporundaki flaglenen satırları `jq` ile süzerken dikkatli olun — kaldırmalar sessizdir. Temizlenmiş dataset'in geçtiğini doğrulamak için sonuç üzerinde her zaman `forgelm audit` koşturun. ::: :::warn diff --git a/docs/usermanuals/tr/deployment/chat.md b/docs/usermanuals/tr/deployment/chat.md index 6500bb85..baec49f4 100644 --- a/docs/usermanuals/tr/deployment/chat.md +++ b/docs/usermanuals/tr/deployment/chat.md @@ -11,7 +11,7 @@ description: Akışlı REPL'de fine-tuned modelinizi sınayın. ```shell $ forgelm chat ./checkpoints/customer-support -ForgeLM 0.5.5 — checkpoints/customer-support ile sohbet +ForgeLM 0.7.0 — checkpoints/customer-support ile sohbet forgelm> aboneliği nasıl iptal ederim? Aboneliğinizi Ayarlar → Faturalandırma → Aboneliği İptal Et adımlarıyla iptal edebilirsiniz. Erişiminiz mevcut faturalama döneminin sonuna kadar @@ -131,7 +131,7 @@ v1 vs v2 win rate: 0.62 (sig p=0.04) ::: :::tip -Birçok prompt'un otomatik sondalanması için interaktif REPL yerine `forgelm batch-chat --prompts data/probes.jsonl --output responses.jsonl` kullanın. Aynı model, manuel yazma yok. +Birçok prompt'u otomatik sondalarken toplu güvenlik taraması için `forgelm safety-eval` kullanın ya da her prompt'u `forgelm chat`'e besleyen ve çıktıyı toplayan bir döngü yazın. Mevcut sürümde ayrı bir batch-chat subcommand'ı bulunmamaktadır. ::: ## Bkz. diff --git a/docs/usermanuals/tr/deployment/deploy-targets.md b/docs/usermanuals/tr/deployment/deploy-targets.md index e7202882..f4d71e24 100644 --- a/docs/usermanuals/tr/deployment/deploy-targets.md +++ b/docs/usermanuals/tr/deployment/deploy-targets.md @@ -28,7 +28,7 @@ $ ollama run my-bot | `tgi` | `tgi-launcher.sh` + Dockerfile | HuggingFace'in text-generation-inference. | | `hf-endpoints` | `endpoints-config.json` | HuggingFace Inference Endpoints'a tek-tıkla deploy. | -KServe ve NVIDIA Triton v0.5.5'te **dahili** hedef değildir. `forgelm deploy --target` parser'ı yalnızca yukarıdaki dört runtime'ı kabul eder. KServe / Triton'da servis sunan operatörler `InferenceService` manifest'ini veya `model_repository/` layout'unu GGUF / safetensors artefakt'ından elle yazar. +KServe ve NVIDIA Triton **dahili** hedef değildir. `forgelm deploy --target` parser'ı yalnızca yukarıdaki dört runtime'ı kabul eder. KServe / Triton'da servis sunan operatörler `InferenceService` manifest'ini veya `model_repository/` layout'unu GGUF / safetensors artefakt'ından elle yazar. ## Ollama @@ -47,7 +47,7 @@ PARAMETER temperature 0.7 PARAMETER top_p 0.9 PARAMETER stop "<|im_end|>" -# customer-support v1.2.0 checkpoint'inden ForgeLM 0.5.5 ile üretildi +# customer-support v1.2.0 checkpoint'inden ForgeLM ile üretildi ``` ForgeLM modelin tokenizer'ına dayanarak doğru `PARAMETER` satırlarını seçer (chat template, stop token) — manuel konfigürasyon gerekmez. @@ -124,18 +124,22 @@ Veya tek-tıkla deployment için HuggingFace UI'sına yapıştırın. ## Konfigürasyon -```yaml -deployment: - target: "vllm" - served_model_name: "customer-support-v1.2" - max_input_length: 4096 - max_total_tokens: 8192 - gpu_memory_utilization: 0.85 - chat_template: "default" # veya .jinja dosyası yolu - system_prompt_default: "Sen..." +`deployment:` üst-düzey YAML bloğu mevcut değildir — `ForgeConfig` `extra="forbid"` ile bilinmeyen anahtarları reddeder. Deploy, eğitimden sonra çağrılan açık bir CLI subcommand'ıdır; YAML-güdümlü otomatik bir adım değildir. + +Hedef ve çıktı yolu doğrudan komut satırından geçirilir: + +```shell +$ forgelm deploy ./checkpoints/run \ + --target vllm \ + --output vllm.yaml ``` -YAML'da `deployment:` varsa `forgelm` son adım olarak (eval / güvenlik geçtikten sonra) `deploy`'u otomatik çalıştırır. +`forgelm deploy` için temel flag'ler: + +| Flag | Açıklama | +|---|---| +| `--target ` | `ollama`, `vllm`, `tgi`, `hf-endpoints`'ten biri. | +| `--output ` | Üretilen config'in yazılacağı dosya veya dizin. | ## Otomatik tespit edilen diff --git a/docs/usermanuals/tr/evaluation/benchmarks.md b/docs/usermanuals/tr/evaluation/benchmarks.md index 039c1f34..7c83f8a1 100644 --- a/docs/usermanuals/tr/evaluation/benchmarks.md +++ b/docs/usermanuals/tr/evaluation/benchmarks.md @@ -1,11 +1,11 @@ --- title: Benchmark Entegrasyonu -description: lm-evaluation-harness görevlerini görev başı floor eşikleriyle ve otomatik geri almayla koşturun. +description: lm-evaluation-harness görevlerini ortalama doğruluk alt sınırı ve otomatik geri almayla koşturun. --- # Benchmark Entegrasyonu -ForgeLM, [lm-evaluation-harness](https://github.com/EleutherAI/lm-evaluation-harness) ile entegre — LLM'ler için standart benchmark suite'i — ve üzerine üretim katmanını ekler: görev başı floor eşikleri, regresyonda otomatik geri alma ve compliance paketinize akan yapılandırılmış artifact'lar. +ForgeLM, [lm-evaluation-harness](https://github.com/EleutherAI/lm-evaluation-harness) ile entegre — LLM'ler için standart benchmark suite'i — ve üzerine üretim katmanını ekler: minimum ortalama doğruluk alt sınırı, regresyonda otomatik geri alma ve compliance paketinize akan yapılandırılmış artifact'lar. ## Hızlı örnek @@ -14,18 +14,15 @@ evaluation: benchmark: enabled: true tasks: ["hellaswag", "arc_easy", "truthfulqa", "mmlu"] - floors: - hellaswag: 0.55 - arc_easy: 0.70 - truthfulqa: 0.45 - num_fewshot: 0 # zero-shot eval + min_score: 0.55 # tüm görevler arası ortalama doğruluk alt sınırı + num_fewshot: 0 # zero-shot eval batch_size: 8 output_dir: "./checkpoints/run/artifacts/" ``` -Eğitimden sonra ForgeLM listelenen görevleri koşturur, floor'larla karşılaştırır ve: -- Tüm görevler floor'u geçerse → koşu başarılı (exit 0) -- Herhangi bir görev floor altına düşerse → son-iyi checkpoint'e otomatik geri al, exit 3 +Eğitimden sonra ForgeLM listelenen görevleri koşturur, ortalama skoru hesaplar ve: +- Ortalama skor `min_score`'u karşılıyorsa veya aşıyorsa → koşu başarılı (exit 0) +- Ortalama skor `min_score`'un altına düşerse → son-iyi checkpoint'e otomatik geri al, exit 3 ## Desteklenen görevler @@ -43,29 +40,26 @@ Eğitimden sonra ForgeLM listelenen görevleri koşturur, floor'larla karşıla Türkçe projeler için ForgeLM, Türkçe-özgü görevlere uyarlanmış `mmlu_tr` ve `belebele_tr` şablonları yayınlar. -## Görev başı floor +## Doğruluk alt sınırı -Floor'lar, görev başına post-train'in geçeceği minimum kabul edilebilir puanı tanımlar. *Her* görev kendi floor'unu geçmeden model terfi etmez. +`min_score`, listelenen tüm görevler genelinde minimum kabul edilebilir post-train **ortalama** puanı tanımlar. Model yalnızca ortalama doğruluk bu değeri karşıladığında veya aştığında terfi eder. ```yaml evaluation: benchmark: - floors: - hellaswag: 0.55 - mmlu: 0.50 - # floor'suz görevler raporlanır ama terfiyi engellemez - truthfulqa: 0.45 + tasks: ["hellaswag", "mmlu", "truthfulqa"] + min_score: 0.50 # ortalama doğruluk alt sınırı (0.0–1.0) ``` -`null` floor "raporla ama gating yapma" demek. `0` floor floor olmamasıyla aynı. +`min_score` `null` olduğunda (varsayılan), benchmark'lar çalıştırılır ve sonuçlar kaydedilir, ancak skor terfini engellemez. `0.0` değeri alt sınır olmamasıyla eşdeğerdir. :::tip -Floor'ları pre-training baseline'ınızdan biraz altına ayarlayın. Hedef: *iyileştirme* zorunlu kılmak değil, *gerilemeyi* yakalamak. Hedef görevde %5 kazanan ama hellaswag'da %2 kaybeden model genelde iyidir; hellaswag'da %15 kaybeden bozuktur. +`min_score`'u pre-training ortalama baseline'ınızdan biraz altına ayarlayın. Hedef: *iyileştirme* zorunlu kılmak değil, *gerilemeyi* yakalamak. Hedef görevde %5 kazanan ama hellaswag'da %2 kaybeden model genelde iyidir; ortalaması %15 düşen bozuktur. ::: ## Pre-train baseline -Hangi floor'u koyacağınızı bilmek için bir pre-training baseline lazım. `--benchmark-only` flag'ini (eğitim yapmadan mevcut bir modeli değerlendirir) tasks + output path'i pin'leyen bir config ile kullanın: +Hangi `min_score`'u koyacağınızı bilmek için bir pre-training baseline lazım. `--benchmark-only` flag'ini (eğitim yapmadan mevcut bir modeli değerlendirir) tasks + output path'i pin'leyen bir config ile kullanın: ```yaml # baseline.yaml @@ -81,16 +75,13 @@ $ forgelm --config baseline.yaml --benchmark-only "Qwen/Qwen2.5-7B-Instruct" {"hellaswag": 0.61, "arc_easy": 0.75, "truthfulqa": 0.49, "mmlu": 0.52} ``` -Makul bir floor baseline eksi 0.03 (stokastik dalgalanma için %3 pay): +Makul bir alt sınır baseline ortalaması eksi 0.03 (stokastik dalgalanma için %3 pay): ```yaml evaluation: benchmark: - floors: - hellaswag: 0.58 # baseline 0.61 - 0.03 - arc_easy: 0.72 - truthfulqa: 0.46 - mmlu: 0.49 + tasks: ["hellaswag", "arc_easy", "truthfulqa", "mmlu"] + min_score: 0.56 # baseline ortalaması ~0.59 - 0.03 ``` ## Çıktı artifact'ları @@ -129,16 +120,16 @@ CI hatları `verdict`'i parse eder. Gating mantığı için bkz. [Otomatik Geri |---|---|---|---| | `enabled` | bool | `false` | Ana anahtar. | | `tasks` | list | `[]` | lm-eval-harness görev adları. | -| `floors` | dict | `{}` | Görev başı minimum kabul edilebilir puan. | -| `num_fewshot` | int | `0` | Zero-shot için 0, 5-shot için 5. | -| `batch_size` | int | `8` | Eval batch size. | +| `min_score` | float | `null` | Minimum ortalama doğruluk alt sınırı (0.0–1.0). Ortalama skor bu değerin altına düşünce otomatik geri alma tetiklenir. | +| `num_fewshot` | int | `null` | Few-shot örnek sayısı. `null` her görevin belgelenmiş varsayılanını kullanır. | +| `batch_size` | string | `"auto"` | Eval batch size: `"auto"` veya bir tamsayı string. | | `limit` | int | `null` | Görev başı satır sınırı — hızlı smoke test için. | -| `device` | string | `"cuda:0"` | Eval cihazı. | +| `output_dir` | string | `null` | Benchmark sonuçları JSON'ının kaydedileceği yer. Varsayılan olarak eğitim `output_dir`. | ## Sık hatalar :::warn -**Pre-train baseline'dan yüksek floor.** Floor'u base modelin geçemediği değere koyarsanız her koşu başarısız olur — otomatik geri alma devreye girer ve hiç checkpoint alamazsınız. Her zaman `baseline - margin` ile başlayın. +**`min_score`'u pre-train baseline ortalamasından yüksek ayarlamak.** `min_score`'u base modelin ortalama görev skorunun üstüne koyarsanız her koşu başarısız olur — otomatik geri alma devreye girer ve hiç checkpoint alamazsınız. Her zaman `baseline ortalaması - margin` ile başlayın. ::: :::warn @@ -151,6 +142,6 @@ CI hatları `verdict`'i parse eder. Gating mantığı için bkz. [Otomatik Geri ## Bkz. -- [Otomatik Geri Alma](#/evaluation/auto-revert) — floor'lar başarısız olduğunda ne olur. +- [Otomatik Geri Alma](#/evaluation/auto-revert) — `min_score` karşılanmadığında ne olur. - [LLM-as-Judge](#/evaluation/judge) — benchmark ötesi nitel eval. - [Trend İzleme](#/evaluation/trend-tracking) — koşular arası puanları karşılaştırma. diff --git a/docs/usermanuals/tr/getting-started/first-run.md b/docs/usermanuals/tr/getting-started/first-run.md index e7da3012..4dbe45dc 100644 --- a/docs/usermanuals/tr/getting-started/first-run.md +++ b/docs/usermanuals/tr/getting-started/first-run.md @@ -37,7 +37,7 @@ forgelm doctor — environment check [✓ pass] gpu.inventory 1 GPU(s) — GPU0: NVIDIA RTX 4090 (24.0 GiB). [✓ pass] extras.qlora Installed (module bitsandbytes, purpose: 4-bit / 8-bit QLoRA training). [✓ pass] extras.unsloth Installed (module unsloth, purpose: Unsloth-accelerated training (Linux GPUs only)). - [! warn] extras.deepspeed Optional extra missing — install with: pip install 'forgelm[deepspeed]' (purpose: DeepSpeed ZeRO + offload distributed training). + [! warn] extras.distributed Optional extra missing — install with: pip install 'forgelm[distributed]' (purpose: DeepSpeed ZeRO + offload distributed training). [✓ pass] hf_hub.reachable HuggingFace Hub reachable (HTTP 200). [✓ pass] disk.workspace Workspace /home/me/forgelm — 387.0 GiB free of 500.0 GiB. [! warn] operator.identity FORGELM_OPERATOR not set; audit events will fall back to 'me@workstation'. Pin FORGELM_OPERATOR= for CI / pipeline runs. diff --git a/docs/usermanuals/tr/operations/cicd.md b/docs/usermanuals/tr/operations/cicd.md index 77c3a84a..99bf9b96 100644 --- a/docs/usermanuals/tr/operations/cicd.md +++ b/docs/usermanuals/tr/operations/cicd.md @@ -13,7 +13,7 @@ ForgeLM, CI/CD hattının bir adımı olarak temiz şekilde yerleşmek üzere ta |---|---|---| | `0` | Başarı | Artifact'ları terfi ettir | | `1` | Konfigürasyon hatası | Hızlıca başarısız ol; YAML'ı düzelt, sonra dene | -| `2` | Audit uyarıları | İncelenmeden merge engellensin | +| `2` | Eğitim hatası | Hızlıca başarısız ol; kilitlenmeyi / OOM / işlenmeyen istisnayı araştır | | `3` | Otomatik geri alma tetiklendi | Başarısız olarak işaretle; gerilemeyi araştır | | `4` | İnsan onayı bekliyor | Hattı askıya al; reviewer'ı tetikle | diff --git a/docs/usermanuals/tr/operations/iso-soc2-deployer.md b/docs/usermanuals/tr/operations/iso-soc2-deployer.md index b197f5c8..94f67d5c 100644 --- a/docs/usermanuals/tr/operations/iso-soc2-deployer.md +++ b/docs/usermanuals/tr/operations/iso-soc2-deployer.md @@ -23,7 +23,7 @@ Derin rehber her birini tam `jq` / CLI komutu + döndürdüğü artefakt ile yan 1. "Son 90 gündeki her model promotion için audit trail'i göster" → `forgelm verify-audit` + `jq 'select(.event == "human_approval.granted")'`. 2. "Bana change-control kanıtını göster — bu modeli kim onayladı?" → `training.started` + `human_approval.granted` olaylarını çapraz referans alın; iki farklı operator ID, görev ayrılığını (segregation of duties) kanıtlar (ISO A.5.3, SOC 2 CC1.5). 3. "Veri lineage'ını göster" → `data_provenance.json`; `sha256` + `hf_revision` corpus'u pinler. -4. "Tedarik zincirini göster" → `gh release download v0.5.5 --pattern 'sbom-*'`; CycloneDX 1.5 JSON. +4. "Tedarik zincirini göster" → `gh release download v0.7.0 --pattern 'sbom-*'`; CycloneDX 1.5 JSON. 5. "Erişim kontrollerini göster" → IdP audit log + `FORGELM_OPERATOR` çapraz referansı. 6. "Şifreleme duruşunu göster" → operatör-tarafı substrate (KMS audit log + `data_governance_report.json`). 7. "Olay müdahalesini göster" → `audit.classifier_load_failed` + F-compliance-110 strict gate. diff --git a/docs/usermanuals/tr/operations/supply-chain.md b/docs/usermanuals/tr/operations/supply-chain.md index 0f4d0410..e53e9b90 100644 --- a/docs/usermanuals/tr/operations/supply-chain.md +++ b/docs/usermanuals/tr/operations/supply-chain.md @@ -19,7 +19,7 @@ ForgeLM sürüm tag'i başına bir CycloneDX 1.5 SBOM yayınlar ve `pip-audit` + ```bash # Bir sürüm için tüm SBOM'lar. -gh release download v0.5.5 --pattern 'sbom-*' +gh release download v0.7.0 --pattern 'sbom-*' # Birini güzel-yazdır. jq . sbom-ubuntu-latest-py3.11.json | less diff --git a/docs/usermanuals/tr/reference/configuration.md b/docs/usermanuals/tr/reference/configuration.md index 29a7e5a4..6ae11865 100644 --- a/docs/usermanuals/tr/reference/configuration.md +++ b/docs/usermanuals/tr/reference/configuration.md @@ -7,23 +7,28 @@ description: ForgeLM'in anladığı her YAML alanı — tipler, varsayılanlar, Bu, ForgeLM'in kabul ettiği her YAML alanının kanonik referansıdır. Şema Pydantic ile zorlanır; `forgelm --config X.yaml --dry-run` dosyanızı şemaya karşı doğrular. -Üst seviye config 12 bloktan oluşur: +Üst seviye config 15 bloktan oluşur: ```yaml model: {...} lora: {...} -galore: {...} -datasets: [...] training: {...} +data: {...} +auth: {...} evaluation: {...} -synthetic: {...} -merge: {...} +webhook: {...} distributed: {...} +merge: {...} compliance: {...} -output: {...} -auth: {...} +risk_assessment: {...} +monitoring: {...} +synthetic: {...} +retention: {...} +pipeline: {...} ``` +> **Not:** `galore` alanları ayrı bir üst-seviye blok değil, `training:` içinde düz alt-alanlardır (`galore_*` önekiyle). Aşağıdaki [`training:`](#training) bölümüne bakın. + ## `model:` ```yaml @@ -58,22 +63,10 @@ lora: use_rslora: false ``` -## `galore:` (lora alternatifi) +## `data:` ```yaml -galore: - enabled: false # lora.r ile çakışır - rank: 256 - update_proj_gap: 200 - scale: 0.25 - proj_type: "std" - target_modules: ["attn", "mlp"] -``` - -## `datasets:` - -```yaml -datasets: +data: - path: "data/train.jsonl" # gerekli format: "messages" # belirtilmezse otomatik algılanır weight: 1.0 @@ -130,7 +123,7 @@ evaluation: benchmark: enabled: false tasks: [] - floors: {} + min_score: null # görevler arası ortalama skalar taban (kaldırılan per-task floors dict'in yerine) num_fewshot: 0 batch_size: 8 limit: null @@ -159,11 +152,7 @@ evaluation: lookback_runs: 10 drift_p_threshold: 0.05 fail_on_concern: "high" - auto_revert: - enabled: false - last_good_checkpoint: null - notify_on_revert: true - keep_failed_checkpoint: true + auto_revert: false # boolean; EU AI Act yüksek-risk regresyon kapısını etkinleştirmek için true yapın guards: {} ``` @@ -246,30 +235,65 @@ compliance: license: "Apache-2.0" ``` -## `output:` +## `webhook:` ```yaml -output: - dir: "./checkpoints/run" # gerekli - model_card: true - save_format: "safetensors" - save_strategy: "epoch" - save_steps: 500 - webhook: - url: null - template: "slack" - events: [] - # cost_tracking: # yol haritası — henüz uygulanmadı; bkz. GPU Maliyet Tahmini sayfası + risks-and-decisions.md - # enabled: false # forgelm/config.py tarafından honure edilmez (output.cost_tracking yüzeyi yok) - # rate_per_hour: {} - # currency: "USD" - # alert_threshold_usd: null - # halt_threshold_usd: null - gguf: - enabled: false - quant_levels: ["q4_k_m"] - output_dir: "${output.dir}/gguf/" - manifest: true +webhook: + url: null # Slack / Teams / Discord / özel; url_env tercihli + url_env: null # webhook URL'sini taşıyan env değişkeni + notify_on_start: true + notify_on_success: true + notify_on_failure: true + timeout: 10 # HTTP istek zaman aşımı (saniye) + allow_private_destinations: false # küme-içi endpoint'ler için SSRF opt-in + require_https: false # true olduğunda düz http:// URL'leri reddeder + tls_ca_bundle: null # özel CA paketi yolu (kurumsal MITM) +``` + +## `risk_assessment:` + +```yaml +risk_assessment: + intended_use: "" # Madde 9(2)(a): amaçlanan kullanım (serbest metin) + foreseeable_misuse: [] # Madde 9(2)(b): öngörülebilir kötüye kullanım senaryoları + risk_category: "minimal-risk" # unknown | minimal-risk | limited-risk | high-risk | unacceptable + mitigation_measures: [] # Madde 9(2)(c): azaltım adımları + vulnerable_groups_considered: false # Madde 9(2)(b): kırılgan gruplar değerlendirildi mi +``` + +## `monitoring:` + +```yaml +monitoring: + enabled: false # Madde 12 pazar-sonrası izlemeyi etkinleştir + endpoint: "" # İzleme webhook URL'si (Prometheus / Datadog / özel) + endpoint_env: null # endpoint'i geçersiz kılan env değişkeni + metrics_export: "none" # none | prometheus | datadog | custom_webhook + alert_on_drift: true # drift tespitinde webhook uyarısı + check_interval_hours: 24 # izleme periyodu (saat) +``` + +## `retention:` + +```yaml +retention: + audit_log_retention_days: 1825 # varsayılan 5 yıl (Madde 5(1)(e)) + staging_ttl_days: 7 # forgelm reject sonrası staging modelini saklama süresi + ephemeral_artefact_retention_days: 90 # uyumluluk paketleri, denetim raporları + raw_documents_retention_days: 90 # ingest edilen PDF/DOCX/EPUB/TXT/Markdown + enforce: "log_only" # log_only | warn_on_excess | block_on_excess +``` + +## `pipeline:` + +```yaml +pipeline: + output_dir: "./pipeline_run" # pipeline-seviyesi çıktı dizini + stages: # sıralı eğitim aşamaları listesi (min 1) + - name: "sft" + training: { trainer: "sft", epochs: 3 } + - name: "dpo" + training: { trainer: "dpo", epochs: 1 } ``` ## `auth:` @@ -285,7 +309,7 @@ auth: `deployment:` üst-seviye YAML anahtarı yoktur — `ForgeConfig` bilinmeyen anahtarları reddeder (`extra="forbid"`), dolayısıyla eğitim config'inize eklerseniz yükleme anında `ConfigError` fırlar. Deployment knob'ları YAML yerine `forgelm deploy` CLI bayrakları olarak açılır. Canlı target seçenekleri `--target {ollama,vllm,tgi,hf-endpoints}`'dir; tam surface için [Deploy hedefleri sayfasına](#/deployment/deploy-targets) ve [CLI referansına](#/reference/cli) bakın. -> **v0.6.0+ için planlanan:** YAML-destekli `deployment:` bölümü [GitHub'daki Phase 14 pipeline-chains yol haritasında](https://github.com/HodeTech/ForgeLM/blob/main/docs/roadmap.md) (eski v0.5.x placeholder'larından ertelendi). O zamana kadar, üçüncü taraf şablonlarda gördüğünüz herhangi bir "deployment:" YAML'ını bilgilendirici sayın; otoriter olan yalnızca `forgelm deploy` bayraklarıdır. +> **Henüz planlanmadı:** YAML-destekli `deployment:` bölümü v0.7.0 sonrasına ertelenmiştir. O zamana kadar, üçüncü taraf şablonlarda gördüğünüz herhangi bir "deployment:" YAML'ını bilgilendirici sayın; otoriter olan yalnızca `forgelm deploy` bayraklarıdır. ## Bkz. diff --git a/docs/usermanuals/tr/training/distributed.md b/docs/usermanuals/tr/training/distributed.md index ccb9e126..52a38a2c 100644 --- a/docs/usermanuals/tr/training/distributed.md +++ b/docs/usermanuals/tr/training/distributed.md @@ -48,10 +48,10 @@ Unsloth, Llama, Qwen, Mistral ve birkaç model için drop-in optimizasyondur. At ```yaml model: name_or_path: "Qwen/Qwen2.5-7B-Instruct" - use_unsloth: true # ihtiyacınız olan tek bayrak + backend: "unsloth" # ihtiyacınız olan tek bayrak training: - trainer: "sft" + trainer_type: "sft" # ... eğitim config'i değişmez ``` @@ -117,7 +117,7 @@ Hangi backend'i kullanırsanız kullanın, gradient accumulation VRAM'in izin ve ```yaml training: - batch_size: 1 # cihaz başına + per_device_train_batch_size: 1 # cihaz başına gradient_accumulation_steps: 32 # etkili batch = 1 × 32 × num_gpus ``` diff --git a/docs/usermanuals/tr/training/galore.md b/docs/usermanuals/tr/training/galore.md index 5b6b4d3b..96e38f67 100644 --- a/docs/usermanuals/tr/training/galore.md +++ b/docs/usermanuals/tr/training/galore.md @@ -26,34 +26,30 @@ model: load_in_4bit: false # GaLore full precision'ı tercih eder max_length: 4096 -galore: - enabled: true - rank: 256 # LoRA'dan yüksek — projeksiyon rank'i - update_proj_gap: 200 # her N adımda bir yeniden projekte et - scale: 0.25 - proj_type: "std" # std (varsayılan), reverse_std, right, left - training: - trainer: "sft" + trainer_type: "sft" learning_rate: 1.0e-5 # full-FT learning rate, LoRA'nınki değil optimizer: "galore_adamw_8bit" - -output: - dir: "./checkpoints/galore" + galore_enabled: true + galore_rank: 256 # LoRA varsayılanından yüksek (128) — projeksiyon rank'i + galore_update_proj_gap: 200 # her N adımda bir yeniden projekte et + galore_scale: 0.25 + galore_proj_type: "std" # std (varsayılan), reverse_std, right, left + output_dir: "./checkpoints/galore" ``` -`galore.enabled: true` iken ForgeLM otomatik olarak GaLore-uyumlu optimizer'ı kullanır; aynı koşuda `lora` blok'unu konfigüre etmeyin. +`training.galore_enabled: true` iken ForgeLM otomatik olarak GaLore-uyumlu optimizer'ı kullanır; aynı koşuda `lora` bloğunu konfigüre etmeyin. ## Parametreler | Parametre | Tip | Vars. | Açıklama | |---|---|---|---| -| `enabled` | bool | `false` | Ana anahtar. | -| `rank` | int | `256` | Gradient projeksiyon rank'i. Yüksek = full-FT'ye yakın, daha çok bellek. | -| `update_proj_gap` | int | `200` | Yeniden projeksiyon adım aralığı. Düşük = değişen gradient'lere hızlı uyum. | -| `scale` | float | `0.25` | Projekte edilmiş gradient'lerin ölçeği. | -| `proj_type` | string | `"std"` | Projeksiyon yönü. Yakınsama tıkanırsa deneyin. | -| `target_modules` | list | `["attn", "mlp"]` | Hangi modüllerin gradient'leri projekte edilecek. | +| `training.galore_enabled` | bool | `false` | Ana anahtar. | +| `training.galore_rank` | int | `128` | Gradient projeksiyon rank'i. Yüksek = full-FT'ye yakın, daha çok bellek. | +| `training.galore_update_proj_gap` | int | `200` | Yeniden projeksiyon adım aralığı. Düşük = değişen gradient'lere hızlı uyum. | +| `training.galore_scale` | float | `0.25` | Projekte edilmiş gradient'lerin ölçeği. | +| `training.galore_proj_type` | string | `"std"` | Projeksiyon yönü. Yakınsama tıkanırsa deneyin. | +| `training.galore_target_modules` | list | `null` | Hangi modüllerin gradient'leri projekte edilecek. | ## Bellek karşılaştırması @@ -65,7 +61,7 @@ output: | LoRA r=16 | %0.2 | 18 GB | 9 GB (QLoRA) | | **GaLore r=256** | **%100** | **22 GB** | yok | -Yani GaLore r=256 ile 7B modeli tek 24 GB GPU'da full fine-tune edebilirsiniz — kabaca full-precision LoRA ile aynı VRAM, ama her ağırlığa erişimle. +Yani GaLore r=256 ile (göstermelik; gönderilen varsayılan r=128'dir) 7B modeli tek 24 GB GPU'da full fine-tune edebilirsiniz — kabaca full-precision LoRA ile aynı VRAM, ama her ağırlığa erişimle. ## Compute @@ -74,7 +70,7 @@ GaLore adım başına LoRA'dan ~%15-20 daha yavaştır; projeksiyon ve yeniden p ## Sık hatalar :::warn -**GaLore'u LoRA ile birleştirmeye çalışmak.** Bunlar alternatiftir, tamamlayıcı değil. ForgeLM şeması aynı anda `lora.r` ve `galore.enabled` ayarlamayı reddeder. +**GaLore'u LoRA ile birleştirmeye çalışmak.** Bunlar alternatiftir, tamamlayıcı değil. ForgeLM şeması aynı anda `lora.r` ve `training.galore_enabled` ayarlamayı reddeder. ::: :::warn diff --git a/docs/usermanuals/tr/training/long-context.md b/docs/usermanuals/tr/training/long-context.md index ac55ec7e..877ea39b 100644 --- a/docs/usermanuals/tr/training/long-context.md +++ b/docs/usermanuals/tr/training/long-context.md @@ -35,20 +35,19 @@ flowchart LR model: name_or_path: "Qwen/Qwen2.5-7B-Instruct" max_length: 32768 - rope_scaling: - type: "linear" - factor: 4.0 # 8K base × 4 = 32K - sliding_window: 4096 # 4K pencerelerde işle load_in_4bit: true training: - trainer: "sft" + trainer_type: "sft" packing: true # throughput için kritik neftune_noise_alpha: 5.0 # eğitim-zamanı embedding gürültüsü + rope_scaling: + type: "linear" + factor: 4.0 # 8K base × 4 = 32K + sliding_window_attention: 4096 # 4K pencerelerde işle -datasets: - - path: "data/long-docs.jsonl" - format: "messages" +data: + dataset_name_or_path: "data/long-docs.jsonl" ``` ## RoPE scaling tipleri @@ -93,9 +92,10 @@ Packing'li: [örnek1][örnek2][örnek3][örnek4][örnek5] ```yaml training: packing: true - packing_max_length: 32768 # genelde = max_length ``` +Maksimum paketlenmiş dizi uzunluğunu kontrol etmek için `model.max_length` ayarlayın. + :::warn Packing örneklerin bağımsız olduğunu varsayar. Tam bağlamı koruması gereken uzun dokümanlarda (kitap bölümleri, kaynak kod repo'ları) `packing: false` ayarlayın. ::: diff --git a/docs/usermanuals/tr/training/lora.md b/docs/usermanuals/tr/training/lora.md index 3c818153..b952f416 100644 --- a/docs/usermanuals/tr/training/lora.md +++ b/docs/usermanuals/tr/training/lora.md @@ -64,7 +64,7 @@ lora: modules_to_save: [] # full-precision modüller (ör. embedding) training: - trainer: "sft" + trainer_type: "sft" learning_rate: 2.0e-4 # LoRA full FT'den yüksek LR tolere eder ``` diff --git a/docs/usermanuals/tr/training/simpo.md b/docs/usermanuals/tr/training/simpo.md index 3c30c397..31132517 100644 --- a/docs/usermanuals/tr/training/simpo.md +++ b/docs/usermanuals/tr/training/simpo.md @@ -70,6 +70,7 @@ ForgeLM `loss_type`, `length_normalize` veya `label_smoothing`'i yapılandırıl |---|---|---|---| | 7B | 16 | 4096 | 9 GB | | 13B | 16 | 4096 | 16 GB | +| 8B | 32 | 8192 | 18 GB | ## `simpo_beta` ve `simpo_gamma` From 4f3b6740fb616506b345fcb41ac6155707189124 Mon Sep 17 00:00:00 2001 From: Cemil ILIK Date: Mon, 15 Jun 2026 18:59:23 +0300 Subject: [PATCH 3/7] docs(guides+qms+design): fix accuracy + bilingual currency (post-#63 audit) guides: library_api __version__/__api_version__ (0.5.5/0.5 -> 0.7.0/1.0.0), troubleshooting exit-code 5 row, gdpr_erasure staging_ttl_days removal v0.7.0->v0.8.0, safety_compliance staging-dir wording, pipeline/alignment/cicd accuracy, performance-tr drift. qms: encryption_at_rest staging path final_model.staging., access_control/incident/risk_treatment EN<->TR currency. design: cache-split + gdpr + iso27001 spec-vs-shipped accuracy. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/design/data_audit_cli_split.md | 2 +- docs/design/gdpr_erasure.md | 4 ++-- docs/design/iso27001_soc2_alignment.md | 5 +++-- docs/guides/alignment-tr.md | 8 ++------ docs/guides/alignment.md | 2 +- docs/guides/cicd_pipeline-tr.md | 1 - docs/guides/cicd_pipeline.md | 2 +- docs/guides/data_audit-tr.md | 7 ++++--- docs/guides/gdpr_erasure-tr.md | 4 ++-- docs/guides/gdpr_erasure.md | 4 ++-- docs/guides/library_api-tr.md | 6 +++--- docs/guides/library_api.md | 6 +++--- docs/guides/performance-tr.md | 2 +- docs/guides/pipeline-tr.md | 2 +- docs/guides/pipeline.md | 2 +- docs/guides/safety_compliance-tr.md | 4 ++-- docs/guides/safety_compliance.md | 4 ++-- docs/guides/troubleshooting-tr.md | 3 ++- docs/guides/troubleshooting.md | 3 ++- docs/qms/access_control-tr.md | 4 ++-- docs/qms/access_control.md | 4 ++-- docs/qms/encryption_at_rest-tr.md | 2 +- docs/qms/encryption_at_rest.md | 2 +- docs/qms/risk_treatment_plan-tr.md | 2 +- docs/qms/risk_treatment_plan.md | 2 +- docs/qms/sop_incident_response-tr.md | 17 +++++++++++------ docs/qms/sop_incident_response.md | 15 ++++++++++----- docs/qms/statement_of_applicability-tr.md | 2 +- docs/qms/statement_of_applicability.md | 2 +- 29 files changed, 66 insertions(+), 57 deletions(-) diff --git a/docs/design/data_audit_cli_split.md b/docs/design/data_audit_cli_split.md index 60d63271..dd8dbbee 100644 --- a/docs/design/data_audit_cli_split.md +++ b/docs/design/data_audit_cli_split.md @@ -597,7 +597,7 @@ A PR in either series is "accepted" when ALL of the following hold: 10. **ruff format + ruff check clean.** 11. **No new top-level imports of torch / transformers / unsloth / deepspeed / lm_eval inside `forgelm/cli/**` or `forgelm/data_audit/**`.** 12. **Logger names unchanged.** -13. **Public exit codes preserved:** `EXIT_SUCCESS == 0`, `EXIT_CONFIG_ERROR == 1`, `EXIT_TRAINING_ERROR == 2`, `EXIT_EVAL_FAILURE == 3`, `EXIT_AWAITING_APPROVAL == 4`, `_PUBLIC_EXIT_CODES == frozenset({0,1,2,3,4})`. +13. **Public exit codes preserved:** `EXIT_SUCCESS == 0`, `EXIT_CONFIG_ERROR == 1`, `EXIT_TRAINING_ERROR == 2`, `EXIT_EVAL_FAILURE == 3`, `EXIT_AWAITING_APPROVAL == 4`, `EXIT_WIZARD_CANCELLED == 5`, `_PUBLIC_EXIT_CODES == frozenset({0,1,2,3,4,5})`. --- diff --git a/docs/design/gdpr_erasure.md b/docs/design/gdpr_erasure.md index 309d2fce..ec097e6b 100644 --- a/docs/design/gdpr_erasure.md +++ b/docs/design/gdpr_erasure.md @@ -80,14 +80,14 @@ Two pre-existing surfaces overlap with this design and must be resolved up front **Conflict-resolution semantics (dual-set window v0.5.5–v0.6.x):** - - When only `evaluation.staging_ttl_days` is set → alias-forward to `retention.staging_ttl_days` and emit a single `DeprecationWarning` naming the new field + the v0.7.0 removal target. + - When only `evaluation.staging_ttl_days` is set → alias-forward to `retention.staging_ttl_days` and emit a single `DeprecationWarning` naming the new field + the v0.8.0 removal target. - When only `retention.staging_ttl_days` is set → no warning; canonical path. - In the case where **both** are set with **identical** values → emit `DeprecationWarning` for the deprecated field; the canonical `retention.staging_ttl_days` value is used; the operator's intent is unambiguous. - If **both** are set with **different** values → raise `ConfigError` at validation time naming both keys, both values, and instructing the operator to remove the deprecated entry. Silent winner = wrong winner; ambiguous configs are refused. Phase 21 ships `tests/test_config.py::test_staging_ttl_days_dual_set_with_different_values_refused` asserting the `ConfigError` and that the message mentions both keys + both values. - **Tracking issue (per `docs/standards/release.md:95`):** Phase 21 also files a tracking issue `'Remove EvaluationConfig.staging_ttl_days in v0.7.0'` and links it from both the `DeprecationWarning` message text and the v0.5.5 CHANGELOG `### Deprecated` entry. The v0.7.0 removal PR closes that issue. + **Tracking issue (per `docs/standards/release.md:95`):** Phase 21 also files a tracking issue `'Remove EvaluationConfig.staging_ttl_days in v0.8.0'` and links it from both the `DeprecationWarning` message text and the v0.5.5 CHANGELOG `### Deprecated` entry. The v0.8.0 removal PR closes that issue. - **`docs/usermanuals/en/compliance/gdpr.md` lines 51-64** + closure plan §15.5 row GH-023 reference an `ingestion.retention.raw_documents.ttl_days` shape. This design (§10 Q1) standardises on the top-level `retention.*` form because the policy covers more than ingestion artefacts (audit logs, staging dirs, ephemeral snapshots). Phase 21 updates the GDPR user-manual page in the same PR; closure plan §15.5 GH-023 entry is amended to "absorbed under top-level `retention.*`" rather than carrying the `ingestion.retention.*` shape forward. ### 3.2 Schema diff --git a/docs/design/iso27001_soc2_alignment.md b/docs/design/iso27001_soc2_alignment.md index 96a4668c..0972d41a 100644 --- a/docs/design/iso27001_soc2_alignment.md +++ b/docs/design/iso27001_soc2_alignment.md @@ -122,7 +122,8 @@ auditable evidence. Cited symbols are real (verified against | HTTP discipline | `safe_post` (Phase 7) | SSRF guard, TLS-only, no-redirect, header masking | | Data audit pipeline | `forgelm audit` (Phase 11) | `data_audit_report.json` (PII / secrets / dedup) | | Annex IV §8 governance | `_data_governance_block` (compliance.py) | `data_governance_report.json` Article 10 | -| Model integrity | `generate_model_integrity` (delegates to `_hash_file`) | `model_integrity.json` | +| Model integrity generation | `generate_model_integrity` (delegates to `_hash_file`) | `model_integrity.json` | +| Model-integrity manifest verification | `forgelm verify-integrity` (Wave 2b / Art. 15) | exit 0/1/2, JSON envelope | | SBOM | `tools/generate_sbom.py` (Wave 2 era) | CycloneDX 1.5 JSON per (OS, py-version), uploaded as release artefact | | Bilingual EN+TR docs | `tools/check_bilingual_parity.py` (Phase 24) | strict-mode diff exit code | @@ -251,7 +252,7 @@ ForgeLM contributes nothing here. | A.8.21 Security of network services | FL-helps | TLS-only webhooks; `FORGELM_AUDIT_SECRET` HMAC | TLS 1.2+ enforcement; cert rotation | | A.8.22 Segregation of networks | OOS | — | VPC / subnet design | | A.8.23 Web filtering | OOS | — | Egress proxy | -| A.8.24 Use of cryptography | FL | SHA-256 + HMAC-SHA-256 (audit chain key = `SHA-256(FORGELM_AUDIT_SECRET ‖ run_id)`, see `forgelm/compliance.py:104-114`); salted SHA-256 identifier hashing for purge / reverse-pii (`_purge._resolve_salt`, distinct concern) | KMS for `FORGELM_AUDIT_SECRET` | +| A.8.24 Use of cryptography | FL | SHA-256 + HMAC-SHA-256 (audit chain key = `SHA-256(FORGELM_AUDIT_SECRET ‖ run_id)`, see `AuditLogger.__init__`, `forgelm/compliance.py:164`); salted SHA-256 identifier hashing for purge / reverse-pii (`_purge._resolve_salt`, distinct concern) | KMS for `FORGELM_AUDIT_SECRET` | | A.8.25 Secure development life cycle | FL-helps | `docs/standards/code-review.md` + `docs/standards/release.md` + CI gates (ruff, pytest, dry-run, parity, SBOM) | SDLC framework | | A.8.26 Application security requirements | FL-helps | F-compliance-110 strict gate; Pydantic config validation; ReDoS guard in `_reverse_pii` | App-level threat modelling | | A.8.27 Secure system architecture and engineering principles | FL-helps | Append-only audit log architecture (`flock`+`fsync` per line); audit chain HMAC; lazy import discipline; `safe_post` SSRF guard | Defence-in-depth design | diff --git a/docs/guides/alignment-tr.md b/docs/guides/alignment-tr.md index 44a3f067..1797a61b 100644 --- a/docs/guides/alignment-tr.md +++ b/docs/guides/alignment-tr.md @@ -61,8 +61,7 @@ Ya da modern `messages` formatı: ```yaml model: name_or_path: "meta-llama/Llama-3.1-8B-Instruct" - max_length: 4096 - backend: "transformers" + load_in_4bit: true lora: r: 16 @@ -266,10 +265,7 @@ forgelm --config configs/stage2_dpo.yaml forgelm --config configs/stage3_grpo.yaml ``` -> **Planlanan (Faz 14 — pipeline chains):** Tek bir YAML dosyasında -> çok-aşamalı eğitim zincirlerini tanımlayan bir `pipeline:` config -> anahtarı, aşamalar arası manuel config curating'i ortadan kaldıracak. -> Takip issue'su v0.6.0+ release penceresine bağlı. +> **v0.7.0'dan itibaren mevcut (Faz 14):** `pipeline:` config bloğu, tek bir YAML'da çok-aşamalı eğitimi (SFT → DPO → GRPO) zincirler. Tam kılavuz için [Çok Aşamalı Eğitim Pipeline'ları](pipeline-tr.md) sayfasına bakın. --- diff --git a/docs/guides/alignment.md b/docs/guides/alignment.md index 36096960..07e134f7 100644 --- a/docs/guides/alignment.md +++ b/docs/guides/alignment.md @@ -227,7 +227,7 @@ forgelm --config configs/stage2_dpo.yaml forgelm --config configs/stage3_grpo.yaml ``` -> **Planned (Phase 14 — pipeline chains):** A `pipeline:` config key will define multi-stage training chains in a single YAML file, eliminating manual config juggling between stages. Tracking issue links the v0.6.0+ release window. +> **Available since v0.7.0 (Phase 14):** The `pipeline:` config block chains multi-stage training (SFT → DPO → GRPO) in a single YAML. See [Multi-Stage Training Pipelines](pipeline.md) for the full guide. --- diff --git a/docs/guides/cicd_pipeline-tr.md b/docs/guides/cicd_pipeline-tr.md index 6970272f..0fe0afad 100644 --- a/docs/guides/cicd_pipeline-tr.md +++ b/docs/guides/cicd_pipeline-tr.md @@ -116,7 +116,6 @@ stages: - validate - train - evaluate - - deploy validate: stage: validate diff --git a/docs/guides/cicd_pipeline.md b/docs/guides/cicd_pipeline.md index b3f70df5..46156b04 100644 --- a/docs/guides/cicd_pipeline.md +++ b/docs/guides/cicd_pipeline.md @@ -8,7 +8,7 @@ ForgeLM is built for automation. This guide shows how to integrate fine-tuning i ForgeLM's CI/CD-native design provides: - **YAML-driven**: Entire training runs defined in version-controlled config files -- **Meaningful exit codes**: `0` success, `1` config error, `2` training error, `3` eval failure +- **Meaningful exit codes**: `0` success, `1` config error, `2` training error, `3` eval failure, `4` awaiting approval - **JSON output**: `--output-format json` for machine-readable results - **Dry-run validation**: `--dry-run` validates without GPU - **Webhook notifications**: Real-time Slack/Teams alerts on start/success/failure diff --git a/docs/guides/data_audit-tr.md b/docs/guides/data_audit-tr.md index 9bc74def..5cc4981c 100644 --- a/docs/guides/data_audit-tr.md +++ b/docs/guides/data_audit-tr.md @@ -192,9 +192,10 @@ Faz 11.5 simhash backend'ini de değiştirilebilir hale getirdi: - **xxhash.xxh3_64** opsiyonel `xxhash` bağımlılığı (artık `forgelm[ingestion]`'ın parçası) yüklüyse per-token digest'i bu - sürüyor; kısa anahtarlarda BLAKE2b'ye göre Python katmanında ~%30 - hızlandırma sağlıyor (lru_cache devreye girince end-to-end kazanç - daha az; backend swap'i öncelikle ileriye dönük güvence). + sürüyor; ~1.3x ham digest başına, ~1.05x end-to-end (Apple Silicon / + Python 3.11 ölçümü) hızlandırma sağlıyor (`compute_simhash` içinde + `lru_cache` tekrar eden token'ları absorbe ettiğinden end-to-end + kazanç daha az; backend swap'i öncelikle ileriye dönük güvence). - **BLAKE2b** bare install için fallback olarak kalıyor. - Modül seviyesinde `lru_cache(maxsize=10_000)` digest'i token seviyesinde memoize ediyor — Zipfian token frekansı sayesinde küçük diff --git a/docs/guides/gdpr_erasure-tr.md b/docs/guides/gdpr_erasure-tr.md index 7ba344fc..acac00dc 100644 --- a/docs/guides/gdpr_erasure-tr.md +++ b/docs/guides/gdpr_erasure-tr.md @@ -93,7 +93,7 @@ Wave 1 `evaluation.staging_ttl_days` field'ı (v0.5.5'te shipped) **deprecate** - İkisi de **aynı** değerlerle açıkça set'liyse `DeprecationWarning` yayılır (canonical block kazanır). - İkisi de **farklı** değerlerle açıkça set'liyse config-load zamanında `ConfigError` raise edilir. Sessiz kazanan = yanlış kazanan. -Deprecate edilen field **v0.7.0**'da kaldırılır. +Deprecate edilen field **v0.8.0**'da kaldırılır. ## Audit-event sözlüğü @@ -185,5 +185,5 @@ glob); `2` = runtime hatası (mid-scan I/O failure). JSON envelope ## Bkz. - `docs/qms/sop_data_management.md` — retention + erasure prosedürleri dahil tam data-lifecycle SOP. -- `docs/usermanuals/tr/compliance/safety_compliance.md` — buraya link veren operator-facing compliance overview. +- `docs/usermanuals/tr/compliance/overview.md` — buraya link veren operator-facing compliance overview. - [`docs/design/gdpr_erasure.md`](../design/gdpr_erasure.md) — bu implementation'ın gerçekleştirdiği Phase 20 design dokümanı. diff --git a/docs/guides/gdpr_erasure.md b/docs/guides/gdpr_erasure.md index 1a770756..7998d6ee 100644 --- a/docs/guides/gdpr_erasure.md +++ b/docs/guides/gdpr_erasure.md @@ -93,7 +93,7 @@ The Wave 1 `evaluation.staging_ttl_days` field (shipped in v0.5.5) is **deprecat - Setting both explicitly with **identical** values emits a `DeprecationWarning` (the canonical block wins). - Setting both explicitly with **different** values raises `ConfigError` at config-load time. Silent winner = wrong winner. -The deprecated field is removed in **v0.7.0**. +The deprecated field is removed in **v0.8.0**. ## Audit-event vocabulary @@ -184,5 +184,5 @@ for the JSON envelope schema. ## See also - `docs/qms/sop_data_management.md` — the full data-lifecycle SOP including the retention + erasure procedures. -- `docs/usermanuals/en/compliance/safety_compliance.md` — the operator-facing compliance overview that links here. +- `docs/usermanuals/en/compliance/overview.md` — the operator-facing compliance overview that links here. - [`docs/design/gdpr_erasure.md`](../design/gdpr_erasure.md) — the Phase 20 design document that this implementation realises. diff --git a/docs/guides/library_api-tr.md b/docs/guides/library_api-tr.md index af1cf8e3..54bfc91c 100644 --- a/docs/guides/library_api-tr.md +++ b/docs/guides/library_api-tr.md @@ -12,7 +12,7 @@ ForgeLM **eşit derecede first-class iki giriş noktası** yayınlar: shell pipe **CLI**'yı seçin: -- Bir Bash / GitHub Actions / GitLab CI pipeline yayınlıyorsanız. Exit-code kontratı (0/1/2/3/4) entegrasyon yüzeyidir. +- Bir Bash / GitHub Actions / GitLab CI pipeline yayınlıyorsanız. Exit-code kontratı (0/1/2/3/4/5) entegrasyon yüzeyidir. - ForgeLM'in stdout'a kutudan çıkar çıkmaz yaydığı yapılandırılmış logging + JSON envelope'larını istiyorsanız. - Aşama başına bir process'in operasyonel birim olduğu altyapıda (çoğu CI runner, çoğu Argo pipeline) çalışıyorsanız. @@ -47,8 +47,8 @@ assert "torch" not in sys.modules # Ama public yüzey autocomplete için tam keşfedilebilir. print("ForgeTrainer" in dir(forgelm)) # True -print(forgelm.__version__) # ör. "0.5.5" -print(forgelm.__api_version__) # ör. "0.5" +print(forgelm.__version__) # ör. "0.7.0" +print(forgelm.__api_version__) # ör. "1.0.0" ``` Wheel ile birlikte yayınlanan çalıştırılabilir bir notebook (`notebooks/library_api_example.ipynb`) bu sayfanın kapsadığı aynı üç deseni yürür — provenance için tasarım dokümanı Faz 19 görev #13'e bakın. diff --git a/docs/guides/library_api.md b/docs/guides/library_api.md index cad4f768..26ca5659 100644 --- a/docs/guides/library_api.md +++ b/docs/guides/library_api.md @@ -12,7 +12,7 @@ ForgeLM ships **two equally first-class entry points**: the `forgelm` console sc Choose the **CLI** when: -- You're shipping a Bash / GitHub Actions / GitLab CI pipeline. The exit-code contract (0/1/2/3/4) is the integration surface. +- You're shipping a Bash / GitHub Actions / GitLab CI pipeline. The exit-code contract (0/1/2/3/4/5) is the integration surface. - You want the structured logging + JSON envelopes ForgeLM emits to stdout out of the box. - You're running on infrastructure where one process per stage is the operational unit (most CI runners, most Argo pipelines). @@ -47,8 +47,8 @@ assert "torch" not in sys.modules # But the public surface is fully discoverable for autocomplete. print("ForgeTrainer" in dir(forgelm)) # True -print(forgelm.__version__) # e.g. "0.5.5" -print(forgelm.__api_version__) # e.g. "0.5" +print(forgelm.__version__) # e.g. "0.7.0" +print(forgelm.__api_version__) # e.g. "1.0.0" ``` A runnable notebook (`notebooks/library_api_example.ipynb`) ships with the wheel and walks the same three patterns this page covers — see the design doc Phase 19 task #13 for its provenance. diff --git a/docs/guides/performance-tr.md b/docs/guides/performance-tr.md index 30c6346a..0b385a3f 100644 --- a/docs/guides/performance-tr.md +++ b/docs/guides/performance-tr.md @@ -192,4 +192,4 @@ GaLore belleği compute ile takas eder. Projeksiyon matris çarpımı gerçek ov - [`library_api-tr.md`](library_api-tr.md) — bu düğmeleri Python'dan çağırma. - [`../standards/coding.md`](../standards/coding.md) — ForgeLM'in dayattığı lazy-import standardı. - [`ingestion-tr.md`](ingestion-tr.md) — chunker kullanıcı-bakışlı derinlik. -- [`alignment.md`](alignment-tr.md) — GaLore + 4-bit + packing'in ne zaman uygun olduğu. +- [`alignment-tr.md`](alignment-tr.md) — GaLore + 4-bit + packing'in ne zaman uygun olduğu. diff --git a/docs/guides/pipeline-tr.md b/docs/guides/pipeline-tr.md index fcfdc65e..6e865a94 100644 --- a/docs/guides/pipeline-tr.md +++ b/docs/guides/pipeline-tr.md @@ -1,6 +1,6 @@ # Çok Aşamalı Eğitim Pipeline'ları -Faz 14 — `v0.7.0` ile geliyor (CHANGELOG kaydı 2026-05-14; PyPI tag bekleniyor). +Faz 14 — `v0.7.0` ile gönderildi (2026-05-14). ForgeLM'in `pipeline:` config bloğu, 2 veya daha fazla eğitim aşamasını (genellikle SFT → DPO → GRPO) tek bir config-tabanlı, dry-run-doğrulanabilir, diff --git a/docs/guides/pipeline.md b/docs/guides/pipeline.md index bd3cef3d..579dd7b0 100644 --- a/docs/guides/pipeline.md +++ b/docs/guides/pipeline.md @@ -1,6 +1,6 @@ # Multi-Stage Training Pipelines -Phase 14 — landing in `v0.7.0` (CHANGELOG entry dated 2026-05-14; PyPI tag pending). +Phase 14 — shipped in `v0.7.0` (2026-05-14). ForgeLM's `pipeline:` config block chains 2 or more training stages (typically SFT → DPO → GRPO) into one config-driven, dry-run-validatable, diff --git a/docs/guides/safety_compliance-tr.md b/docs/guides/safety_compliance-tr.md index 8972538a..da016bcb 100644 --- a/docs/guides/safety_compliance-tr.md +++ b/docs/guides/safety_compliance-tr.md @@ -350,7 +350,7 @@ require_hmac=False)`, bir `VerifyResult` dataclass'ı (`valid`, ```json { - "forgelm_version": "0.5.5", + "forgelm_version": "0.7.0", "generated_at": "2026-03-23T14:30:00+00:00", "model_lineage": { "base_model": "meta-llama/Llama-3.1-8B-Instruct", @@ -478,7 +478,7 @@ evaluation: **Ne olur:** 1. Eğitim tamamlanır, tüm otomatik değerlendirmeler geçer -2. Model nihai dizine kaydedilir +2. Model staging dizinine kaydedilir (`final_model.staging./`) 3. ForgeLM **kod 4** ("onay bekleniyor") ile çıkar 4. Bir insan değerlendirme sonuçlarını, model card'ı ve uyumluluk artefaktlarını inceler diff --git a/docs/guides/safety_compliance.md b/docs/guides/safety_compliance.md index c488dbcb..588d09ab 100644 --- a/docs/guides/safety_compliance.md +++ b/docs/guides/safety_compliance.md @@ -305,7 +305,7 @@ The library function `forgelm.compliance.verify_audit_log(path, *, hmac_secret=N ```json { - "forgelm_version": "0.5.5", + "forgelm_version": "0.7.0", "generated_at": "2026-03-23T14:30:00+00:00", "model_lineage": { "base_model": "meta-llama/Llama-3.1-8B-Instruct", @@ -431,7 +431,7 @@ evaluation: **What happens:** 1. Training completes, all automated evaluations pass -2. Model is saved to the final directory +2. Model is saved to the staging directory (`final_model.staging./`) 3. ForgeLM exits with **code 4** ("awaiting approval") 4. A human reviews the evaluation results, model card, and compliance artifacts 5. The human approves or rejects the model diff --git a/docs/guides/troubleshooting-tr.md b/docs/guides/troubleshooting-tr.md index da290656..dc113f7b 100644 --- a/docs/guides/troubleshooting-tr.md +++ b/docs/guides/troubleshooting-tr.md @@ -197,7 +197,7 @@ synthetic: max_new_tokens: 512 # asılı kalıyorsa teacher yanıt boyutunu sınırla ``` -`SyntheticConfig`, v0.5.5'te ayrı retry / batch ayarları yüzeylemiyor — +`SyntheticConfig`, v0.7.0'da ayrı retry / batch ayarları yüzeylemiyor — retry'lar HTTP-client katmanında ele alınır ve batch size API çağrısı başına bir prompt'a sabittir. Phase 28+ backlog'u açık retry-count ve batched-call parametreleri eklemeyi takip ediyor. @@ -414,6 +414,7 @@ docker run --gpus all --shm-size=16g ... | `2` | Eğitim hatası | GPU, bellek, bağımlılıkları kontrol edin | | `3` | Değerlendirme arızası | Model kalitesi eşiğin altında — eşikleri ayarlayın ya da veriyi iyileştirin | | `4` | Onay bekleniyor | İnsan incelemesi gerekli — staging dizinini incelemek için `forgelm approvals --show --output-dir ` çalıştırın, sonra promote için `forgelm approve --output-dir ` ya da kalıcı reject için `forgelm reject --output-dir `. Staging yolu `/final_model.staging./`'dir. | +| `5` | Sihirbaz iptal | Sihirbaz iptal edildi (Ctrl-C veya açık iptal) — config yazılmadı; `--wizard` ile yeniden çalıştırın ya da etkileşimsiz kullanım için `forgelm quickstart