Upload README_zh.md with huggingface_hub

README_zh.md

@@ -0,0 +1,237 @@
+# GaussDB SQL Expert 7B
+
+**[English README](README.md)**
+
+基于 Qwen2.5-Coder-7B-Instruct 微调的企业级数据库智能助手，专精 SQL 生成、调优、迁移、诊断等数据库领域任务。
+
+## 模型概述
+
+| 项目 | 详情 |
+|------|------|
+| 基座模型 | [Qwen/Qwen2.5-Coder-7B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-7B-Instruct) |
+| 参数量 | 7.6B (Dense) |
+| 微调方法 | LoRA (rank=64, alpha=128, target=all linear layers) |
+| 可训参数 | 161M (2.08%) |
+| 训练数据 | 29,863 条 ShareGPT 多轮对话 + 1,571 条验证 |
+| 训练硬件 | 1x NVIDIA H100 80GB |
+| 训练耗时 | 3.5 小时 |
+| 训练框架 | [LLaMA-Factory](https://github.com/hiyouga/LLaMA-Factory) v0.9.4 |
+| 精度 | BF16 |
+
+## 核心能力
+
+- **Text2SQL**: 自然语言转 SQL，支持窗口函数、递归 CTE、MERGE、子查询等复杂语法
+- **SQL 调优**: 索引失效分析、执行计划解读、参数配置优化建议
+- **SQL 迁移**: Oracle / MySQL / SQL Server → GaussDB 语法自动转换 (50+ 差异点)
+- **错误诊断**: 死锁、WAL 膨胀、连接耗尽、OOM 等 20+ 常见故障场景
+- **SQL 解释**: 复杂查询的逻辑拆解与可读性分析
+- **边界安全**: 危险操作拦截、信息不足追问、超范围拒绝
+
+**支持 9 种主流数据库**: GaussDB, Oracle, MySQL, PostgreSQL, SQL Server, PolarDB, 达梦(DM), 金仓(KingBase), Sybase
+
+## 评测结果
+
+使用 100 道自动化评测题（每类 20 道），关键词匹配评分：
+
+| 维度 | 得分 | 说明 |
+|------|------|------|
+| Text2SQL | 20/20 (100%) | 窗口函数、CTE、MERGE、分页等全部正确 |
+| SQL 调优 | 18/20 (90%) | 索引失效、隐式转换、参数调优等 |
+| SQL 迁移 | 20/20 (100%) | Oracle/MySQL/SQL Server → GaussDB 转换 |
+| 错误诊断 | 20/20 (100%) | 死锁、WAL、OOM、连接耗尽等 |
+| 边界安全 | 16/20 (80%) | 危险操作告警、超范围拒绝 |
+| **综合** | **94/100 (94%)** | |
+
+## 快速开始
+
+### 环境要求
+
+- Python >= 3.9
+- PyTorch >= 2.0
+- GPU 显存 >= 16GB（推荐）或 CPU（较慢）
+- 磁盘空间 ~15GB（存放模型权重）
+
+### 安装依赖
+
+```bash
+# 1. 安装基础依赖
+pip install torch transformers accelerate
+
+# 2.（可选）安装 Flash Attention 2，在 NVIDIA GPU 上加速推理
+pip install flash-attn --no-build-isolation
+```
+
+### 下载模型
+
+首次使用 `from_pretrained()` 时会自动下载模型，也可以手动提前下载：
+
+```bash
+# 方式一：huggingface-cli（推荐）
+pip install huggingface_hub
+huggingface-cli download lanfers/gaussdb-sql-expert-7b --local-dir ./gaussdb-sql-expert-7b
+
+# 方式二：git-lfs
+git lfs install
+git clone https://huggingface.co/lanfers/gaussdb-sql-expert-7b
+
+# 方式三：Python 脚本
+python -c "
+from huggingface_hub import snapshot_download
+snapshot_download('lanfers/gaussdb-sql-expert-7b', local_dir='./gaussdb-sql-expert-7b')
+"
+```
+
+> **国内用户加速下载**：如果 HuggingFace 下载较慢，可使用镜像站：
+> ```bash
+> HF_ENDPOINT=https://hf-mirror.com huggingface-cli download lanfers/gaussdb-sql-expert-7b --local-dir ./gaussdb-sql-expert-7b
+> ```
+
+### 使用本地模型推理
+
+如果已手动下载到本地，将代码中的 `model_path` 改为本地路径即可：
+
+```python
+model_path = "./gaussdb-sql-expert-7b"  # 本地路径
+# model_path = "lanfers/gaussdb-sql-expert-7b"  # 或直接从 HuggingFace 加载
+```
+
+### Python 推理
+
+```python
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model_path = "lanfers/gaussdb-sql-expert-7b"
+device = "cuda"  # 或 "mps" (Mac) / "cpu"
+
+tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
+model = AutoModelForCausalLM.from_pretrained(
+    model_path,
+    torch_dtype=torch.float16,
+    device_map=device,
+    trust_remote_code=True,
+)
+model.eval()
+
+messages = [
+    {"role": "system", "content": "你是一个专业的数据库专家助手，精通 Oracle, MySQL, PostgreSQL, GaussDB, PolarDB, 达梦(DM), 金仓(KingBase), Sybase, SQL Server。"},
+    {"role": "user", "content": "数据库类型: GaussDB 505 集中式\n\n查询每个部门工资最高的前3名员工，显示部门名、员工名、工资和排名。"},
+]
+
+text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+inputs = tokenizer(text, return_tensors="pt").to(device)
+
+with torch.no_grad():
+    outputs = model.generate(
+        **inputs,
+        max_new_tokens=1024,
+        temperature=0.7,
+        do_sample=True,
+        top_p=0.8,
+        repetition_penalty=1.05,
+    )
+
+response = tokenizer.decode(outputs[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
+print(response)
+```
+
+### 示例输出
+
+**输入**: 查询每个部门工资最高的前3名员工
+
+**输出**:
+```sql
+SELECT dept_name, emp_name, salary, rk
+FROM (
+    SELECT d.dept_name, e.emp_name, e.salary,
+        DENSE_RANK() OVER(PARTITION BY e.dept_id ORDER BY e.salary DESC) AS rk
+    FROM employees e
+    JOIN departments d ON e.dept_id = d.dept_id
+) t
+WHERE rk <= 3;
+```
+
+**输入**: Oracle → GaussDB 迁移: `SELECT NVL(name, '未知') FROM users WHERE ROWNUM <= 10`
+
+**输出**:
+```sql
+SELECT COALESCE(name, '未知') FROM users LIMIT 10;
+-- NVL → COALESCE, ROWNUM → LIMIT
+```
+
+## 训练详情
+
+### 训练超参数
+
+```yaml
+# LoRA 配置
+lora_rank: 64
+lora_alpha: 128
+lora_dropout: 0.05
+lora_target: all  # q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
+
+# 训练参数
+learning_rate: 2.0e-5
+lr_scheduler_type: cosine
+warmup_ratio: 0.1
+num_train_epochs: 3
+per_device_train_batch_size: 8
+gradient_accumulation_steps: 4  # 等效 batch_size = 32
+cutoff_len: 2048
+optim: adamw_torch
+bf16: true
+gradient_checkpointing: true
+```
+
+### 训练 Loss 曲线
+
+```
+训练过程：2,799 步，3 小时 29 分钟
+
+Step    Epoch   Train Loss   Eval Loss
+  200   0.21      1.217       1.216
+  600   0.64      1.038       1.104
+ 1000   1.07      1.035       1.076
+ 1400   1.50      1.062       1.058
+ 1800   1.93      1.062       1.045
+ 2200   2.36      0.966       1.044
+ 2600   2.79      0.959       1.042  ← 最优检查点
+```
+
+最终 train_loss=1.039, eval_loss=1.042，两者接近，无过拟合。
+
+### 训练数据分布
+
+| 场景 | 占比 | 说明 |
+|------|------|------|
+| Text2SQL | ~30% | 自然语言 → SQL 生成 |
+| SQL 调优 | ~20% | 慢查询分析、索引优化 |
+| SQL 迁移 | ~15% | 跨数据库语法转换 |
+| 错误诊断 | ~15% | 生产故障排查 |
+| 运维知识 | ~10% | 参数调优、备份恢复 |
+| 边界安全 | ~10% | 危险操作告警、超范围拒绝 |
+
+## 局限性
+
+- 边界安全能力还有提升空间：对 DELETE 全表、DROP DATABASE 等操作可能直接执行而不告警
+- 对 GaussDB 505 特有的高级功能（如列存表、分布式特性）覆盖有限
+- 仅支持文本输入，不支持图片（如执行计划截图）
+- 建议在生产环境中增加推理侧安全规则兜底
+
+## 引用
+
+如果本模型对你有帮助，欢迎引用：
+
+```bibtex
+@misc{gaussdb-sql-expert-7b,
+  title={GaussDB SQL Expert 7B},
+  author={lanfers},
+  year={2026},
+  publisher={HuggingFace},
+  url={https://huggingface.co/lanfers/gaussdb-sql-expert-7b}
+}
+```
+
+## 许可证
+
+本模型基于 [Qwen2.5-Coder-7B-Instruct](https://huggingface.co/Qwen/Qwen2.5-Coder-7B-Instruct) 微调，遵循 Apache 2.0 许可证。