Oredelight/grammar-checker
GitHub: Oredelight/grammar-checker
一款结合 LanguageTool 规则引擎与 Google Gemini AI 的混合式英语语法检测与纠错系统，提供 REST API 与交互式 Web 界面。
Stars: 1 | Forks: 0
# Dreamy Checker - 高级语法纠正系统
一个复杂的混合语法检查和纠正系统，它将基于规则的检测与 Google 的 Gemini AI 结合起来以进行智能纠正。Dreamy Checker 通过智能错误检测和上下文感知纠正，提供全面的文本润色。
## 概述
Dreamy Checker 是一款智能语法纠正工具，旨在帮助用户写出更好的英语。该系统利用基于规则和 AI 驱动的方法来进行全面的语法检查：
1. **基于规则的引擎**：LanguageTool 根据全面的英语规则检测语法违规
2. **AI 增强**：Google Gemini API 提供智能的、上下文感知的纠正
3. **智能分块**：通过智能拆分来处理长文档（每个块最多 180 个词）
### 为什么采用混合方法？
- **精准性**：基于规则的引擎能以可靠的模式捕获技术性语法错误
- **智能性**：Gemini AI 能理解上下文并自然地改善流畅度
- **可扩展性**：智能地对文本进行分块，以处理任意长度的文档
- **可靠性**：过滤掉误报和嘈杂的规则
## 功能
### 核心能力
- **混合语法纠正**：将 LanguageTool 基于规则的检查与 Google Gemini AI 相结合
- **双层检测**：第一轮使用 LanguageTool 规则，第二轮使用 AI 分析
- **REST API**：基于 FastAPI 的 endpoint，提供带请求验证的编程式访问
- **交互式 Web UI**：简洁、响应式的界面，支持实时语法检查
- **全面的问题检测**：识别语法错误、拼写、大小写、标点符号等
- **上下文分析**：返回每个检测到的问题的上下文，以帮助用户理解错误
- **智能文本分块**：通过智能拆分来处理长文档（每个块最多 180 个词）
- **智能过滤**：通过过滤嘈杂的 LanguageTool 规则来消除误报
## 技术栈
### 后端架构
| 组件 | 技术 | 用途 |
|-----------|-----------|---------|
| **Web 框架** | FastAPI 0.136.3 | 现代 async API 服务器 |
| **ASGI 服务器** | Uvicorn | 生产就绪服务器 |
| **语法引擎** | language-tool-python 3.4 | 基于规则的错误检测 |
| **AI 提供商** | Google Gemini API | 上下文感知的 AI 纠正 |
| **数据验证** | Pydantic 2.13.4 | 请求/响应验证 |
| **模板引擎** | Jinja2 3.1.6 | HTML 模板渲染 |
| **配置** | python-dotenv | 环境变量管理 |
### 前端技术栈
- **HTML5**：语义化标记
- **CSS3**：响应式设计与自定义样式
- **原生 JavaScript**：DOM 操作与 API 通信
- **设计**：粉色/梦幻主题，兼顾无障碍访问考量
### 关键依赖项说明
```
Core Processing:
- language-tool-python: Comprehensive grammar rules (English)
- google-genai: Google Gemini API client for AI corrections
Web Services:
- fastapi: Async request handling
- uvicorn: Production ASGI server
- jinja2: Template rendering
Data Handling:
- pydantic: Type-safe validation
- python-multipart: Form data parsing
Utilities:
- python-dotenv: Environment configuration
- requests: HTTP client library
```
## 项目架构
### 目录结构
```
grammer-checker/
├── main.py # FastAPI application entry point
├── requirements.txt # Python dependencies with versions
├── README.md # Comprehensive documentation (this file)
│
├── api/ # API layer
│ ├── __init__.py
│ └── routes.py # Grammar checker endpoint definitions
│
├── services/ # Business logic layer
│ ├── __init__.py
│ ├── grammarchecker.py # Core grammar checking orchestration
│ ├── aicorrector.py # Google Gemini AI integration
│ └── schemas.py # Pydantic data models and validators
│
├── evaluation/ # Quality assurance
│ ├── __init__.py
│ ├── evaluate.py # Test execution and reporting
│ └── test_cases.json # Test cases with expected outputs
│
└── templates/ # Frontend
└── index.html # Interactive web UI
```
### 组件交互图
```
┌─────────────────────────────────────────────────────────┐
│ User Interface │
│ (templates/index.html) │
└────────────────────┬────────────────────────────────────┘
│ HTTP POST /check-grammar
▼
┌─────────────────────────────────────────────────────────┐
│ FastAPI Application │
│ (main.py) │
└────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ API Routes Layer │
│ (api/routes.py) │
│ • Input validation (GrammarInput schema) │
│ • Response formatting (GrammarOutput schema) │
└────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Grammar Checker │
│ (services/grammarchecker.py) │
│ Primary orchestration logic: │
│ 1. Initial LanguageTool pass │
│ 2. Extract issues and context │
│ 3. Call Google Gemini AI for corrections │
│ 4. Diff original vs corrected text │
│ 5. Merge and deduplicate issues │
└────┬────────────────────────────┬───────────────────────┘
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────────────┐
│ LanguageTool │ │ Google Gemini AI Service │
│ (Rule-based) │ │ (services/aicorrector.py)│
│ │ │ │
│ • 50+ grammar │ │ • Natural language AI │
│ rules │ │ • Context-aware prompts │
│ • English US │ │ • Intelligent chunking │
│ • Pattern match │ │ • API-based (cloud) │
│ • Fast detection │ │ • Graceful fallback │
└──────────────────┘ └──────────────────────────┘
```
## 安装与设置
### 前置条件
在安装之前，请确保您具备：
- **Python 3.8+**（已在 3.10 和 3.11 版本上测试）
- **pip** 包管理器
- **虚拟环境**支持（venv 或 conda）
- **Google Gemini API 密钥**（可在 https://aistudio.google.com/ 获取免费额度）
- **约 2GB 磁盘空间**：用于存放依赖项
### 逐步安装指南
#### 1. 克隆代码库
```
git clone https://github.com/yourusername/grammer-checker.git
cd grammer-checker
```
#### 2. 创建虚拟环境
```
# 使用 venv（推荐）
python -m venv venv
# 激活 virtual environment
# 在 Windows 上：
venv\Scripts\activate
# 在 macOS/Linux 上：
source venv/bin/activate
```
#### 3. 安装依赖项
```
# 升级 pip
pip install --upgrade pip
# 安装所有依赖
pip install -r requirements.txt
```
#### 4. 设置环境变量
```
# 在项目根目录创建 .env 文件
echo GEMINI_API_KEY=your_api_key_here > .env
# 从以下网址获取你的 API key：https://aistudio.google.com/
```
#### 5. 验证安装
```
# 检查 Python 版本
python --version
# 测试 FastAPI
python -c "import fastapi; print(f'FastAPI {fastapi.__version__}')"
# 测试 language tools
python -c "import language_tool_python; print('Language Tool ready')"
# 测试 Gemini client
python -c "import google.genai; print('Gemini API ready')"
```
## 运行应用程序
### 开发服务器
```
# 以热重载模式运行以进行开发
uvicorn main:app --reload --host 0.0.0.0 --port 8000
# 输出：
# INFO: Uvicorn running on http://0.0.0.0:8000
# INFO: Application startup complete
```
然后打开：`http://localhost:8000/dreamy-checker`
### 生产服务器
```
# 多 worker 生产环境设置
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
```
### 测试安装
```
# 通过 curl 测试
curl -X POST "http://localhost:8000/check-grammar" \
-H "Content-Type: application/json" \
-d '{"text": "He go to the store yesterday."}'
# 预期响应：
# {
# "original": "He go to the store yesterday.",
# "corrected": "He goes to the store yesterday.",
# "issues": [
# {
# "message": "Third person singular...",
# "context": "go"
# }
# ]
# }
```
## API 文档
### Base URL
```
http://localhost:8000
```
### Endpoint 概览
| 方法 | Endpoint | 用途 |
|--------|----------|---------|
| POST | `/check-grammar` | 检查并纠正语法 |
| GET | `/dreamy-checker` | 交互式 Web 界面 |
| GET | `/docs` | Swagger UI 文档 |
| GET | `/redoc` | ReDoc API 文档 |
### 详细 Endpoint 参考
#### 1. 语法检查器 Endpoint
```
POST /check-grammar
```
**用途**：分析文本中的语法错误并返回纠正建议
**Content-Type**：`application/json`
**请求体**：
```
{
"text": "Your text to check for grammar errors."
}
```
**字段说明**：
- `text`（字符串，必填）：要检查的文本
- 最小长度：1 个字符
- 最大长度：无硬性限制（自动分块）
- 不得为空或仅包含空白字符
**请求示例**：
```
# 简单查询
curl -X POST "http://localhost:8000/check-grammar" \
-H "Content-Type: application/json" \
-d '{"text": "The cat are sleeping."}'
# 复杂文本
curl -X POST "http://localhost:8000/check-grammar" \
-H "Content-Type: application/json" \
-d '{
"text": "I have went to the store and buyed some milk. The weather were nice."
}'
# 长文档（自动分块）
curl -X POST "http://localhost:8000/check-grammar" \
-H "Content-Type: application/json" \
-d '{
"text": "Here is a very long text that spans multiple paragraphs and sentences..."
}'
```
**响应**（200 OK）：
```
{
"original": "The cat are sleeping.",
"corrected": "The cat is sleeping.",
"issues": [
{
"message": "Subject-verb agreement: 'cat' is singular but 'are' is plural",
"context": "are"
}
]
}
```
**响应字段**：
- `original`（字符串）：未更改的输入文本
- `corrected`（字符串）：文本的纠正版本
- `issues`（数组）：检测到的语法问题
- `message`（字符串）：错误描述
- `context`（字符串）：导致问题的特定单词/短语
**错误响应**：
422 Unprocessable Entity（文本为空）：
```
{
"detail": [
{
"type": "value_error",
"loc": ["body", "text"],
"msg": "Text cannot be empty",
"input": ""
}
]
}
```
500 Internal Server Error（模型问题）：
```
{
"detail": "Error loading AI model. Check logs for details."
}
```
**响应时间**：
- 冷启动（首次请求，加载模型）：3-5 秒
- 后续请求：0.5-2 秒（平均 1.41 秒）
- 视文本长度和系统资源而定
#### 2. Web 界面 Endpoint
```
GET /dreamy-checker
```
**用途**：提供交互式 Web UI 服务
**响应**：包含嵌入 CSS/JavaScript 的 HTML 页面
**功能**：
- 实时语法检查
- 原文与纠正后文本的并排显示
- 带有上下文的问题列表
- 复制到剪贴板功能
- 漂亮的粉色/梦幻主题
- 响应式移动端设计
#### 3. API 文档
```
GET /docs # Swagger UI
GET /redoc # ReDoc
GET /openapi.json # OpenAPI spec
```
### 用户工作流
```
1. Navigate to /dreamy-checker
2. Paste or type text in input box
3. Click "Fix Grammar" button
4. See errors highlighted, corrected, and issues
5. Copy corrected text or try again
```
## 工作原理
### 双层语法检查流程
**第一层：基于规则的检测 (LanguageTool)**
- 使用 50 多种预定义语法规则检测问题
- 对原始文本进行快速模式匹配
- 提供基于规则的建议
- 过滤掉嘈杂的规则 (SKIP_RULES)
**第二层：AI 驱动的润色 (Google Gemini)**
- 将文本拆分为智能块（最多 180 个词）
- 将每个块连同语法纠正 prompt 一起发送到 Gemini API
- 利用 LLM 的理解能力进行上下文感知的纠正
- 如果 API 不可用，则平滑回退到原始文本
**整合与去重**
- 使用 SequenceMatcher 比较原始文本与 AI 纠正后的文本
- 提取单词级别的差异
- 合并来自两个层的问题
- 移除重复/重叠的问题
- 返回带有上下文的全面问题列表
### API 功能
- **优雅降级**：即使在 Gemini API 不可用时也能工作（返回 LanguageTool 结果）
- **自动分块**：处理任意长度的文档
- **上下文保留**：在纠正语法的同时保持语义
### 运行测试
```
# 执行评估套件
python -m evaluation.evaluate
# 输出包括：
# - 每个类别的测试结果
# - 整体成功指标
# - 平均响应时间
# - 失败用例详情
```
### 测试用例
测试用例存储在 `evaluation/test_cases.json` 中，涵盖：
- 冠词（a/an/the 的用法）
- 大小写（专有名词，句子开头）
- 混合错误（多种问题的组合）
- 所有格（撇号的位置）
- 介词（in/on/at/by 等）
- 代词（he/she/they 的一致性）
- 标点符号（逗号、句号、分号）
- 拼写（拼写错误和错别字）
- 主谓一致（复数/单数匹配）
- 时态（过去时、现在时、将来时的一致性）
### 测试用例结构
测试用例存储在 `evaluation/test_cases.json` 中：
```
[
{
"category": "subject_verb_agreement",
"input": "The dogs runs quickly.",
"expected": "The dogs run quickly."
},
{
"category": "spelling",
"input": "I recieved your message.",
"expected": "I received your message."
}
]
```
### 添加新测试用例
1. 编辑 `evaluation/test_cases.json`
2. 添加包含类别、输入和预期输出的条目
3. 运行评估：
python -m evaluation.evaluate
### 性能故障排除
| 症状 | 可能原因 | 解决方案 |
|---------|---------|----------|
| 未提供纠正建议 | Gemini API 密钥缺失/无效 | 将 GEMINI_API_KEY 添加到 .env |
| API 响应缓慢 | 触发限流 | 检查 Gemini API 配额 |
| 仅返回 LanguageTool 结果 | Gemini API 不可用 | 检查 API 连接，查看日志 |
| 空文本错误 | 无效输入 | 提供非空文本 |
| 文本分块不正确 | 文档过大 | 检查文本格式 |
## 部署
### Docker 部署
**Dockerfile**：
```
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
```
**构建并运行**：
```
# 构建 image
docker build -t dreamy-checker .
# 使用环境变量运行
docker run -p 8000:8000 -e GEMINI_API_KEY=your_key_here dreamy-checker
# 或者使用 .env 文件
docker run -p 8000:8000 --env-file .env dreamy-checker
```
### 如何贡献
1. **Fork** 该代码库
2. **创建**一个功能分支（`git checkout -b feature/amazing-feature`）
3. **提交**您的更改（`git commit -m 'Add amazing feature'`）
4. **推送**到该分支（`git push origin feature/amazing-feature`）
5. **发起**一个 Pull Request
**最后更新**：2026 年 6 月\
**AI 引擎**：Google Gemini API\
**架构**：混合（基于规则 + AI 驱动）
标签：AV绕过, FastAPI, Gemini AI, LanguageTool, 后端开发, 数据可视化, 文本处理, 网络测绘, 语法检查, 逆向工具