AI二次开发
一、模块范围
AI 后端能力集中在 springboot/fastbee-ai，前端页面集中在 vue3/src/views/ai。当前主要覆盖模型供应商、模型配置、对话、对话记录、知识库、协议适配、NL2SQL 和源码知识库。
二、后端接口分组
| 接口前缀 | 用途 |
|---|---|
/ai/chat | AI 对话 |
/ai/chatRecord | 对话记录 |
/ai/provider | 模型供应商 |
/ai/model | 模型配置 |
/ai/knowledge | 知识库 |
/ai/knowledge/document | 知识文档 |
/ai/knowledge/source | 知识来源 |
/ai/knowledge/template | 知识模板 |
/ai/knowledge/runtime | 知识库运行态 |
/ai/knowledge/version | 知识库版本 |
/ai/protocol/adaptation | 协议适配 |
/ai/protocol/knowledge | 协议知识 |
/ai/nl2sql | 自然语言转查询 |
/ai/platform/knowledge | 平台知识 |
/ai/knowledge/codebase | 源码知识库 |
三、新增模型供应商
新增供应商时建议按以下步骤：
- 明确供应商 API 协议、鉴权方式、模型名称和限流规则。
- 在后端模型调用层增加 Provider 适配。
- 在模型配置中补充供应商类型和必要参数。
- 增加连接测试或简单对话验证。
- 补充错误码映射，避免把供应商原始错误直接暴露给用户。
- 在前端表单中增加字段说明和校验。
四、知识库扩展
知识库扩展重点：
| 方向 | 说明 |
|---|---|
| 文档解析 | 支持新的文件格式、编码和抽取方式 |
| 切片策略 | 调整标题层级、段落长度、重叠范围 |
| 向量模型 | 切换或新增 Embedding 模型 |
| 召回策略 | 增加过滤条件、排序、重排模型 |
| 版本管理 | 增强质量评估、发布、回滚 |
| 权限控制 | 按租户、角色、知识库范围隔离 |
五、协议适配扩展
协议适配建议输出结构固定化，便于用户复用：
- 协议概览。
- 连接方式。
- 注册/鉴权流程。
- 报文结构。
- 字段映射表。
- 平台产品配置建议。
- 物模型建议。
- 开发任务拆解。
- 测试用例。
- 常见问题。
如果需要让 AI 生成更稳定的结果，应把协议文档整理成标题清晰、字段表明确、示例完整的知识库资料。
六、NL2SQL扩展
NL2SQL 涉及真实业务数据，开发时必须关注安全边界：
- 只允许查询授权范围内的数据。
- 禁止执行写入、删除、DDL 等危险 SQL。
- 对生成 SQL 做表、字段、租户和分页限制。
- 对时序数据库和关系数据库使用不同查询策略。
- 保留查询计划和用户确认过程。
七、前端开发入口
| 页面 | 目录 |
|---|---|
| AI 对话 | vue3/src/views/ai/chat |
| 对话记录 | vue3/src/views/ai/chatRecord |
| 知识库 | vue3/src/views/ai/knowledge |
| 模型配置 | vue3/src/views/ai/model |
| 协议适配 | vue3/src/views/ai/protocolAdaptation |
| 供应商 | vue3/src/views/ai/provider |
API 封装位于：
text
vue3/src/api/ai八、测试建议
| 类型 | 建议用例 |
|---|---|
| 模型配置 | 密钥正确、密钥错误、模型不存在、超时 |
| 对话 | 普通问题、长上下文、模型失败、取消请求 |
| 知识库 | 上传、解析失败、构建、发布、回滚、禁用文档 |
| 协议适配 | 空资料、结构化资料、错误报文、字段表生成 |
| NL2SQL | 正常查询、越权字段、危险 SQL、空结果 |