docs: 重构文档结构,规范编号并整合冗余内容
## 主要变更 ### 文档重构(减少 1199 行,-23%) - 01-架构设计.md: 503→369 行 (-27%),删除 DDL/配置示例,精简鉴权/存储描述 - 02-接口文档.md: 1313→570 行 (-57%),删除 Go 接口/Orchestrator 实现/配置管理 - 07-成本控制.md: 65→59 行 (-9%),代码块替换为文件引用 ### 文档编号规范化 - 08-功能创意.md → 删除(内容整合到 README.md "功能扩展方向") - 10-Eino框架与编排设计.md → 08-Eino框架与编排设计.md - 情景切换.md → 09-情景切换.md - 12-鉴权体系.md → 10-鉴权体系.md - 13-令牌桶限流.md → 11-令牌桶限流.md ### 交叉引用更新 - 01-架构设计.md: 更新对鉴权体系/令牌桶限流的引用为新编号 - README.md: 更新文档索引表、推荐阅读顺序、新增功能扩展方向 ### 删除过时文档 - 09-技术名词解释.md(内容已整合到 03-技术选型.md) - 10-Eino重构方案.md(历史记录,已完成) - 11-Eino框架技术文档.md(已合并到 08) - 情景切换功能完整文档.md(已规范化为 09) ## 重构原则 - 架构文档聚焦系统结构,移除实现细节 - 接口文档保留纯契约,删除内部实现 - 编号连续(01-11),语义清晰 - 通过交叉引用连接相关文档,避免重复
This commit is contained in:
@@ -4,7 +4,16 @@
|
||||
|
||||
本文档记录项目中各项技术的**选型过程、替代方案对比和决策理由**。技术选型没有"绝对正确",只有"更适合"。
|
||||
|
||||
**定位**:本文档记录各项技术的选型过程和决策理由。
|
||||
各技术选型章节包含关键术语解释,帮助快速理解技术概念。
|
||||
|
||||
### 后端核心技术栈
|
||||
|
||||
| 名词 | 解释 |
|
||||
|------|------|
|
||||
| **Go (Golang)** | 高并发后端语言,Google 开发,杀手锏是 goroutine——极轻量协程,一个程序可轻松开几万个,每个只占几 KB 内存,适合管理大量 WebSocket 长连接 |
|
||||
| **gorilla/websocket** | Go WebSocket 库,Go 标准库无内置 WebSocket 支持,此库是社区最成熟的选择,处理了协议握手、帧解析等底层细节 |
|
||||
| **Viper** | Go 配置管理库,读取 JSON/YAML/TOML 配置,支持环境变量覆盖,方便开发/测试/生产环境用不同配置 |
|
||||
| **Zap** | Go 结构化日志库,Uber 开源,输出 JSON 格式日志,方便工具搜索分析,性能远超标准库 log |
|
||||
|
||||
```
|
||||
技术选型
|
||||
@@ -34,6 +43,18 @@
|
||||
|
||||
## 一、AI 编排框架选型
|
||||
|
||||
### 关键术语
|
||||
|
||||
| 名词 | 解释 |
|
||||
|------|------|
|
||||
| **Eino** | 字节跳动开源的 Go AI 应用开发框架(CloudWeGo Eino),提供 Graph DAG 编排、组件抽象(ChatModel/Tool 等)、流式处理和 Callback AOP 机制 |
|
||||
| **compose.Graph** | Eino 的 DAG 编排器,声明式有向无环图,节点可以是 Lambda、ChatModel、ToolsNode 等,边定义数据流向 |
|
||||
| **Lambda** | Graph 中的可组合函数单元,四种模式:InvokableLambda(同步)、StreamableLambda(流式输出)、CollectableLambda(流式输入)、TransformableLambda(双向流式) |
|
||||
| **StreamReader** | Eino 的流式数据抽象 `schema.StreamReader[T]`,类似 io.Reader 的语义,`Recv()` 读取一帧,`io.EOF` 表示流结束 |
|
||||
| **Callback** | Eino 的 AOP 机制,类似中间件的钩子,支持节点生命周期回调(OnStart/OnEnd/OnError/OnEndWithStreamOutput) |
|
||||
|
||||
> 更多 Eino 相关概念详见 [10-Eino框架与编排设计.md](10-Eino框架与编排设计.md)
|
||||
|
||||
### 候选方案对比
|
||||
|
||||
| 框架 | 语言 | 特点 | CamTalk 适用性 |
|
||||
@@ -74,6 +95,14 @@ github.com/cloudwego/eino-ext/components/model/openai v0.1.13 # OpenAI 兼容 C
|
||||
|
||||
## 二、AI 服务栈选型
|
||||
|
||||
### 关键术语
|
||||
|
||||
| 名词 | 解释 |
|
||||
|------|------|
|
||||
| **多模态 LLM** | 能读文字又能看图片的大语言模型,如 GPT-4o(OpenAI)、Claude Sonnet(Anthropic),给照片+问题能"看懂"照片再回答 |
|
||||
| **STT** | Speech-to-Text,语音转文字。流式识别延迟可低于 500ms |
|
||||
| **TTS** | Text-to-Speech,文字转语音。支持流式——边生成边读,不必等全部生成完 |
|
||||
|
||||
### STT(语音识别)
|
||||
|
||||
| 方案 | 延迟 | 成本 | 特点 |
|
||||
@@ -106,7 +135,15 @@ LLM 通过 Eino 框架的 `eino-ext/components/model/openai` ChatModel 组件接
|
||||
|
||||
---
|
||||
|
||||
## 二、持久化层选型
|
||||
## 三、持久化层选型
|
||||
|
||||
### 关键术语
|
||||
|
||||
| 名词 | 解释 |
|
||||
|------|------|
|
||||
| **PostgreSQL** | 关系型数据库,支持 JSONB(JSON 二进制格式,可建索引)、窗口函数、CTE 等高级特性 |
|
||||
| **Redis** | 内存 KV 数据库,数据放在内存里,读写微秒级。支持 TTL 过期自动清理 |
|
||||
| **MVCC** | Multi-Version Concurrency Control,多版本并发控制,PostgreSQL 用此实现高并发读写而不阻塞 |
|
||||
|
||||
### 数据特征分析
|
||||
|
||||
@@ -220,7 +257,19 @@ Go Gateway (TieredManager)
|
||||
|
||||
---
|
||||
|
||||
## 二、前端边缘处理层选型
|
||||
## 四、前端边缘处理层选型
|
||||
|
||||
### 关键术语
|
||||
|
||||
| 名词 | 解释 |
|
||||
|------|------|
|
||||
| **React 18** | 组件化 UI 框架,Facebook 开源,把页面拆成组件搭积木拼装。18 版本支持并发渲染 |
|
||||
| **TypeScript** | 带类型的 JavaScript,在 JS 基础上增加类型声明,编译阶段就能发现类型错误 |
|
||||
| **Vite** | 前端构建工具,利用浏览器原生 ES Module,开发时毫秒级热更新(HMR),构建产物小 |
|
||||
| **WebSocket** | 浏览器与服务器的双向通道。HTTP 是"一问一答",WebSocket 像打电话——接通后双方随时互发消息,适合实时对话场景 |
|
||||
| **ONNX Runtime Web** | 浏览器端 AI 推理引擎,微软定义的通用模型格式 ONNX 的运行引擎,可在浏览器中用 WASM 加速跑轻量模型(如 VAD、关键帧检测),零延迟、不耗服务器资源 |
|
||||
| **VAD** | Voice Activity Detection,语音活动检测,检测"人有没有在说话"。WebRTC 内置了高效的 VAD 算法 |
|
||||
| **MediaDevices API** | 浏览器摄像头/麦克风接口,`navigator.mediaDevices.getUserMedia()` 是浏览器音视频采集的唯一标准入口,无需插件 |
|
||||
|
||||
### 总览
|
||||
|
||||
@@ -270,7 +319,16 @@ vad-web 是"够用且最轻"的平衡点——直接包装浏览器原生 WebRTC
|
||||
|
||||
---
|
||||
|
||||
## 四、认证与用户系统选型
|
||||
## 五、认证与用户系统选型
|
||||
|
||||
### 关键术语
|
||||
|
||||
| 名词 | 解释 |
|
||||
|------|------|
|
||||
| **JWT** | JSON Web Token,无状态 token,服务端不存 session,分布式友好 |
|
||||
| **HS256** | HMAC-SHA256,JWT 对称签名算法,用同一密钥签名和验证 |
|
||||
| **bcrypt** | 密码哈希算法,自适应 cost factor,抗暴力破解 |
|
||||
| **pgx** | Go 生态性能最优的 PostgreSQL 驱动,原生协议实现,内置连接池 pgxpool |
|
||||
|
||||
### 总览
|
||||
|
||||
|
||||
Reference in New Issue
Block a user