望江坐标系技术细节解析

引言

望江坐标系是一个面向高中语文教学场景的 AI 智能平台，以「作文教学」和「文言文教学」为核心，结合 Deepseek 大模型与本地教研知识库，为师生提供深度、可定制的 AI 辅助教学体验。本文将从技术架构、核心模块、数据流、部署实践和未来方向五个维度，全面解析望江坐标系的技术实现。

整个项目的出发点非常朴素：当前市面上的 AI 作文辅导工具大多只是简单地将用户问题转发给大模型，缺少对教学场景的深度理解。高中语文教学有其特殊性——作文批改需要贴合高考评分标准，知识检索需要精准匹配教材内容，思维训练需要可引导、可修改的交互流程。望江坐标系正是为了解决这些具体问题而生的。

从技术视角来看，这个项目也有其独特之处。它不追求使用最前沿的大模型或最复杂的架构，而是强调「够用就好」——用 FAISS 做向量检索而不引入 Elasticsearch，用 ONNX Runtime 跑 Embedding 而不依赖 GPU，用单 HTML 文件做前端而不上 React/Vue CLI。这种务实的选型思路，使得整个项目可以在一台 2C4G 的轻量云服务器上流畅运行，同时保持了良好的可维护性和可扩展性。

---

一、整体技术架构

望江坐标系采用前后端分离的架构，以 Python FastAPI 作为后端服务，前端支持 Gradio WebUI 和 Vue.js SPA 两种访问方式，适配桌面端与移动端。

1.1 技术栈选型

层级	技术选型	选型理由
后端框架	FastAPI (Python)	异步原生，自动生成 OpenAPI 文档，流式 SSE 推送天然支持
LLM API	Deepseek V4-Pro / V4-Flash	国产大模型，384K 超长上下文，支持 max 推理强度，性价比高
向量检索	FAISS (IndexFlatIP)	零外部依赖，毫秒级检索，内积 = 余弦相似度
Embedding	BAAI/bge-small-zh-v1.5 (ONNX)	中文优化，基于 ONNX Runtime，无 torch 依赖，轻量级
前端 SPA	Vue.js 3 (CDN)	无需构建工具，单 HTML 文件即可部署，适合快速迭代
桌面端	pywebview	原生窗口包装 Web 应用，兼顾开发效率与用户体验
部署	OpenResty + systemd	反向代理 + SSL 终结，容器化管理

1.2 项目结构

望江坐标系/
├─ server.py            # FastAPI 主入口（所有路由）
├─ rag_engine.py        # RAG 引擎（Embedding + 检索 + LLM 调用）
├─ writing_service.py   # 写作服务（批改/出题/范文/建议/逻辑链）
├─ auth.py              # 用户认证 + 权限 + 聊天记录
├─ config.py            # 配置管理 + API Key 加密存储
├─ index.html           # Vue.js 前端（桌面+手机自适应）
├─ control.html         # 管理后台
├─ knowledge_base/      # 教研知识库（~120 篇 Markdown）
├─ vector_db/           # FAISS 向量索引 + metadata
└─ model_cache/         # BGE Embedding 模型缓存

---

二、RAG 引擎核心设计

RAG 引擎是整个平台最核心的基础设施，负责将用户的自然语言问题转化为精准的检索 + 生成链路。选择 RAG 而非微调，主要基于三个考量：其一，知识库内容需要频繁更新（教研资料不断丰富），微调的更新成本过高；其二，RAG 的检索过程可解释、可调试，教师可以清楚地看到 AI 是基于哪些资料给出回答的；其三，不同学科、不同年级的知识库相对独立，RAG 架构天然支持知识隔离。

2.1 检索流程

用户提问 → BGE Embedding → FAISS 向量检索 → Top-K 片段 → 拼接 Prompt → Deepseek API → 流式输出

关键参数：

• 分块策略：500 字符/块，50 字符重叠，按段落 + 句子切分
• 检索数量：Top-K = 5（可配置 1-20）
• 相似度度量：内积（等同于余弦相似度在归一化向量下的结果）
• Embedding 模型：BGE-small-zh-v1.5 (384 维向量)，ONNX Runtime 推理

2.2 知识库构建

知识库包含约 120 篇 Markdown 文档，覆盖作文教学总论、公众号素材、写作语料库、创意写作、议论文教学、课本考纲等 10 大类。构建流程：

# build_index.py 核心逻辑
文档扫描 → MD 文件(≥50字符) → 分块(500字符) → BGE向量化 → FAISS写入

向量索引持久化存储在 vector_db/ 目录下的 index.faiss（约 3.8MB）和 metadata.json（约 2.4MB），支持增量更新和强制重建。

2.3 双路径检索增强

RAG 引擎支持两种上下文来源：

1. 知识库检索：本地教研资料，精确可控
2. 联网搜索：通过 Metaso Search API 获取最新资讯，补充时效性信息

两种来源拼接为统一上下文，传入 LLM 生成回答。可独立开关、灵活组合。

---

三、写作服务模块详解

写作服务是平台的核心业务层，包含五大功能模块。

3.1 智能出题

严格遵循上海高考命题风格的操作流程：

第一步：确定方向 → 第二部：考纲检核 → 第三部：自检清单(5项)
→ 第四部：试写思路 → 第五部：难度定级

每一步都在 Prompt 中强制 Chain-of-Thought（思维链），确保输出符合命题规范。

3.2 思维链写作

这是最核心的教学创新。传统 AI 写作是「一句话生成一篇文章」，而思维链模式将过程拆解为：

输入题目 → 生成 3-5 条逻辑论证链 → 用户选择/修改 → 严格按链写作 → 输出范文

每条逻辑链包含：切入点、核心论点、分论点展开、论证方法、关键论据方向、论证难度评级。用户可以在对话中与 AI 讨论修改逻辑链，确认后再生成范文——确保「思维第一，文采第二」。

3.3 作文批改

五维评分体系：

维度	分值	评估内容
审题立意	10	切题程度、中心突出、立意深度
论证逻辑	10	论点明确性、论据充分性、论证严密性
结构布局	10	结构完整性、段落衔接
语言表达	10	流畅度、语病、用词准确性
素材运用	10	贴切度、新颖性、分析深度

批改结果包含：综合评分、逐段批注、主要问题、亮点、修改建议和升格范文。

3.4 范文生成

支持三种文体（议论文/散文/记叙文），创意度可调（0-1），并可控制联网搜索最新素材。生成结果附带「论证复盘」——用 LLM 自我批判的方式分析论证结构。

---

四、用户系统与安全

4.1 认证体系

users.json 文件存储
├─ 角色: admin / user
├─ 每日配额: 可配置
├─ 密码: SHA256 哈希
└─ 锁定: 5次失败 → 10分钟锁定

4.2 API Key 加密存储

Deepseek / Metaso / 百度 OCR 三种 API Key 使用 XOR 混淆 + Base64 编码加密存储在 .key 文件中，防止明文泄露。具体实现：

_SALT = bytes([87, 74, 51, 88, 89, 45, 50, 48, 50, 53])
def _xor(data): return bytes(b ^ _SALT[i % 10] for i, b in enumerate(data))

加密后的 Key 即使被 accidental commit 到版本控制中，也无法直接读取原文。在打包模式下，Key 文件会持久化到用户的 %APPDATA% 目录，避免与源码混在一起。

4.3 聊天记录

双格式存储：

• chats/{username}.json — 程序读取（最近 500 条）
• chats/{username}.md — 人类可读的 Markdown 格式

每次对话完成后自动保存，支持跨设备查看历史记录。学生在手机上提问后，回到电脑端可以继续查看完整的对话上下文，无需手动同步。

---

五、前端与移动端适配

前端采用 Vue.js 3（CDN 版本），单 HTML 文件即包含完整 UI，无需构建工具。

5.1 自适应设计

通过 CSS @media 实现三种布局：

断点	布局	导航
≥769px	桌面端：两栏并排 + 侧栏	顶部横排 Tab
≤768px	手机端：纵向堆叠	固定底部图标栏

手机端特性：

• 底部导航栏（5 个功能图标）
• 侧栏可折叠（点击标题展开/收起）
• 输入框/按钮最小 44px 触控友好
• 字数 15px 更易读

5.2 SSE 流式更新

所有 AI 对话均通过 Server-Sent Events (SSE) 实现流式输出，前端逐 chunk 解析 JSON，实时渲染 Markdown 结果，提供打字机效果。

---

六、部署实践

6.1 服务器架构

外部请求 → OpenResty (Docker) → SSL 终结 → 反向代理 → FastAPI (systemd)
                                                               │
                                                         ┌─────┴─────┐
                                                         │ knowledge_base │
                                                         │ vector_db  │
                                                         └────────────┘

部署采用 1Panel 面板管理 OpenResty 反向代理，后端以 systemd 服务形式运行。这种架构的优势在于：

• 反向代理层负责 SSL 终结、静态资源缓存、请求转发，与后端逻辑解耦
• systemd 服务保证后端进程崩溃后自动重启，开机自启
• 多站点共存通过不同的 location 路径映射到同一后端的不同路由

6.2 Nginx 代理配置

location /composition {
    proxy_pass http://127.0.0.1:7862;
    # ... 标准代理头设置 ...
}

关键的代理配置要点：

• proxy_buffering off：禁用缓冲，确保 SSE 流式输出实时到达客户端
• proxy_read_timeout 600s：LLM 推理可能耗时较长，超时时间要充足
• proxy_set_header Host $host：保持原始 Host 头，方便后端区分多站点

6.3 多站点结构（2026.06）

当前线上运行的服务：

https://wjzbx.tco3.cn/             导航站 (Hexo)
https://wjzbx.tco3.cn/composition  望江坐标系·作文 (FastAPI)
https://wjzbx.tco3.cn/control      管理后台 (FastAPI)
https://tco3.cn/                   博客 (Hexo, 本文所在)

三个站点的关系：

1. 导航站作为门户入口，以卡片形式展示各个子项目
2. 作文应用是核心产品，承载完整的 AI 辅助教学功能
3. 博客记录技术细节和更新日志

6.4 运维与监控

后端服务的日志管理通过 systemd journal 完成：

systemctl status wangjiang      # 查看服务状态
journalctl -u wangjiang -f      # 实时查看日志

Nginx 层面的访问日志记录在 /www/sites/wjzbx.tco3.cn/log/ 目录，通过分析日志可以了解请求量、响应时间、错误分布。

6.5 开发工作流

项目的开发工作流采用本地预览 + 远程部署的模式：

1. 本地开发：在 Windows 环境下直接运行 python server.py，使用本地知识库和远程 Deepseek API
2. 本地验证：curl http://127.0.0.1:7862/api/stats 确认服务正常
3. 远程部署：通过 paramiko SSH 上传变更文件，systemctl restart wangjiang 重启服务

这种工作流的优势在于代价小、迭代快。整个部署脚本只有不到 200 行 Python，核心就是 SFTP 上传 + SSH 执行命令。

6.6 开发过程中的挑战与解决

在望江坐标系的开发过程中，有几个技术挑战值得记录：

挑战一：旧版 .doc 文档的解析
教研资料中有大量 .doc 格式的旧版文档，与标准 .docx 不同，无法直接用 python-docx 解析。最终采用多路径方案：优先通过 Word COM 接口将 .doc 转为 .docx 后解析（可保留加点字格式），COM 失败时再回退到 olefile 文本提取并辅以智能加点字重建算法。

挑战二：SSE 流式输出的稳定性
LLM 推理时间较长（通常在 5-30 秒），SSE 长连接在反向代理环境下容易超时断开。通过在 Nginx 层设置 proxy_read_timeout 600s 和 proxy_buffering off，同时在应用层实现断线重连机制解决问题。

挑战三：移动端自适应布局
Vue.js 前端最初仅面向桌面端设计，在手机上的体验很差。改造的关键在于：

• 将顶部导航替换为固定底部导航栏
• 两栏布局改为纵向堆叠，侧栏可折叠
• 所有交互元素最小化触控尺寸

挑战四：知识库中文乱码
百词斩等文件的表格包含大量加点字（混合粗体+斜体样式），通过 Word COM 转换 + 智能加点字重建算法（基于解释文本关键词匹配），最终将 11 个百词斩文件中的加点字全部正确标记。

---

七、未来更新方向

7.1 文言文教学平台（即将上线）

「望江坐标系·文言」是紧随作文之后的第二个核心产品。目前知识库已准备完成，覆盖人教版高一下学期全部文言篇目。

已完成的知识库构建（2026.06）：

数据来源	文件数	内容
剪报	10	学术文章、原文译文对照（鸿门宴、报任安书等）
校本古诗文	22	逐课配套练习 + 答案 + 加点字标注
百词斩	11	词汇训练，例句 + 释义配对

知识库总量约 700KB，包含详尽的教学资料。其中「加点字」标记（**字**）是文言文教学的关键设计——通过解析 Word 文档中的粗体+斜体格式，自动识别需要重点讲解的字词，让 AI 在回答中精准定位考点。

文言平台预计提供的功能：

• 字词释义：实词虚词精准解释，通假字、词类活用自动识别
• 文段翻译：逐段对照翻译，重点字词悬浮释义
• 文常背景：作者生平、时代背景、典章制度
• 练习批改：自动批改校本练习和百词斩练习
• 智能问答：基于知识库的精准文言文答疑

7.2 对话记录与知识管理

2. 对话记录增强

   • 支持按日期/标签检索历史对话
   • 对话摘要自动生成
   • 导出为 PDF / Markdown 格式

3. 知识库管理后台

   • 在线编辑器：直接在网页上编写和修改知识库文档
   • 一键重建索引：修改知识库后自动触发向量索引更新
   • 版本管理：追踪知识库变更历史
   • 权限控制：不同用户可访问不同的知识库

7.3 技术优化方向

4. 多模型智能路由

   • 根据问题类型自动选择模型：简单问答走 Flash（更低延迟），复杂推理走 V4-Pro（更强能力）
   • 据估算，约 60% 的日常问题可通过 Flash 处理，可降低约 40% 的 API 成本

5. RAG 检索引擎升级

   • 引入混合检索：结合 BM25 稀疏检索与 Dense 向量检索，取长补短
   • 检索重排序：使用 Cross-Encoder 对召回结果重新排序，将最相关片段提到最前
   • 自适应窗口压缩：根据上下文长度动态调整检索数量，避免超出模型上下文限制

6. 性能与可靠性提升

   • 连接池复用：减少每次 LLM 调用的握手开销
   • 增量索引：修改知识库时只重新索引变更部分，而非全量重建
   • 结果缓存层：高频重复问题直接命中缓存，秒级响应
   • 降级策略：Deepseek API 不可用时自动切换到备用模型

7.4 开放平台规划

7. 开发者生态

   • OpenAI 兼容 API 接口，允许第三方应用接入
   • 知识库接入规范，支持自定义文档格式
   • Prompt 模板市场，用户可分享和复用优秀的教学 Prompt

8. 数据闭环

   • AI 回答的用户反馈（点赞/点踩）
   • 基于反馈的在线学习优化
   • 教学效果数据分析看板

7.5 长期愿景

望江坐标系的最终目标不是取代教师，而是成为教师手中最趁手的 AI 工具。通过持续积累高质量的教学知识库、不断优化 AI 对教学场景的理解，让技术真正服务于课堂。

在技术层面，我们希望探索的方向包括：

• 多模态理解：支持图片（手写作文 OCR）、语音（口语表达训练）
• 自适应学习路径：根据学生的薄弱环节智能推荐练习内容
• 协作批改：AI 初批 + 教师终审的工作流支持
• 离线运行：将 Embedding 模型和轻量 LLM 部署到本地，满足无网络环境的使用需求

---

结语

望江坐标系从构思到上线历时数月，核心设计理念是「技术服务于教学」——用 RAG 技术让 AI 回答有据可依，用思维链模式让写作过程可理解、可修改、可优化，用移动端适配让师生随时随地可用。

回顾整个开发过程，最大的感悟是：AI 教育产品的核心不在于模型有多强，而在于对教学场景的理解有多深。一个好的 AI 作文助手，不仅要能写出漂亮的文章，更要能说清楚「为什么这么写」「还有哪些写法」「你的问题出在哪里」。望江坐标系的思维链模式，正是对这一理念的具体实践。

未来，我们将持续迭代产品功能，完善文言文教学平台，优化检索和推理性能，让 AI 真正成为高中语文教学的有力助手。欢迎关注 tco3.cn 博客，获取最新的更新动态和技术分享。