qyyfw/qihuaiflow

0 Fork 0

Files

T

QihuAI Design ec7de645f4

CI / gate (push) Has been cancelled

Details

docs-add-architecture-blueprint

2026-07-27 09:10:11 +08:00

19 KiB

Raw Blame History

七虎AI PaaS 平台 — 架构设计与实施方案 v2.0

最后更新: 2026-07-27 版本: v2.0 用途: 投喂 AI 大模型进行平台竞争力、护城河、扩展能力分析维护: 随系统迭代实时更新

一、平台概述

1.1 定位

七虎AI（qihuyun.com）是一个面向开发者和企业的 AI PaaS 平台，核心能力是聚合多厂商大模型、提供标准化工具调用层、支持 Skill/MCP/Agent 的发现-安装-编排-执行全生命周期管理。

1.2 核心价值主张

价值维度	实现方式
模型聚合	统一 OpenAI 兼容协议接入 4+ 厂商（SiliconFlow、MiMo、AGNES、DeepSeek），自动 failover
技能市场	Skills 的上架-搜索-安装-执行闭环，支持 14 个能力分类
MCP 协议	官方 Anthropic MCP SDK 实现，支持 streamable_http/SSE 传输
Agent 编排	DAG 图引擎 + Supervisor 模式，支持外部 Agent（Dify/n8n/Coze）远程调用
IM Bot	多平台（微信/企业微信/飞书/QQ）统一消息网关
知识库 RAG	PostgreSQL pgvector + 混合检索
媒体生成	异步图片/视频生成（后台线程，不阻塞 SSE）
可观测	Prometheus+Grafana 监控栈 + 日志审计

二、整体架构

2.1 部署架构

                    Internet
                        │
                   ┌────▼────┐
                   │  Nginx  │  :12888 (HTTPS)
                   └────┬────┘
                        │
         ┌──────────────┼──────────────┐
         │              │              │
    ┌────▼────┐    ┌───▼────┐    ┌───▼─────┐
    │ React   │    │FastAPI │    │ Casdoor │
    │ Vite    │    │uvicorn │    │  :8000  │
    │ (dist/) │    │:18080  │    └─────────┘
    └─────────┘    └───┬────┘
                       │
         ┌─────────────┼─────────────┐
         │             │             │
    ┌────▼────┐   ┌───▼────┐   ┌───▼──────┐
    │Postgres │   │ Redis  │   │ Executor │
    │PG18+    │   │:6379   │   │ (Code)   │
    │pgvector │   └────────┘   └──────────┘
    └─────────┘

2.2 容器清单

容器	镜像	用途
qihu-aiflow	自建(custom)	主应用（Nginx + FastAPI uvicorn + React dist）
qihu-aiflow-pg18	pgvector/pgvector:pg16	PostgreSQL 主库 + 向量扩展
qihu-aiflow-redis	redis:7-alpine	缓存/队列/会话
qihu-aiflow-casdoor	casdoor	统一认证
qihuaiflow-executor	自建	代码执行沙箱
qihu-aiflow-prometheus	prom/prometheus	指标采集
qihu-aiflow-grafana	grafana/grafana	可视化监控
qihu-aiflow-alloy	grafana/alloy	日志采集 Agent
qihu-aiflow-node-exporter	prom/node-exporter	宿主机指标

2.3 数据流

用户请求 → Nginx(:12888) → uvicorn(:18080)
  ├── /app/api/chat/* → chat.py (SSE streaming)
  ├── /app/api/auth/* → auth.py (JWT)
  ├── /app/api/admin/* → admin/* (CRUD + 管理)
  └── / → index.html → React SPA

三、技术栈矩阵

层级	技术	版本	选型理由
后端框架	FastAPI (Python)	0.115+	异步原生、SSE 流式支持、Pydantic 验证
ASGI 服务器	uvicorn	0.30+	单进程事件循环、生产级
前端框架	React + Vite	18 + 5	组件化、HMR 热更新、Tree-shaking
前端语言	TypeScript	5.6+	类型安全
关系数据库	PostgreSQL	18	JSONB、pgvector 原生支持、AIO 引擎
向量引擎	pgvector	0.8.4	与主库同集群、免运维
缓存	Redis	7	会话、队列、工具列表缓存
认证	Casdoor	latest	开源统一认证、OAuth2/OIDC
ORM	SQLAlchemy	2.0.36	成熟生态、支持 async
LLM 客户端	openai Python SDK	1.x	OpenAI 兼容协议统一接入
MCP 客户端	mcp Python SDK	1.28.1	Anthropic 官方 SDK
代理	Nginx	1.25+	反向代理、静态文件、SSL
容器	Docker Compose	v2	单机编排
监控	Prometheus + Grafana	latest	开源标准、全栈可见

四、数据模型（67 张表，按域分组）

4.1 核心业务域

表名	说明	关键字段
users	用户	id, username, password_hash, role
conversations	对话	id, user_id, title, model_id
messages	消息	id, conv_id, role, content, tool_calls, used_skills
models	AI 模型	id, provider_id, name, endpoint, capabilities, is_default
model_providers	模型提供商	id, name, protocol, api_key, api_base_url, auth_header
site_settings	站点配置	key, value (JSON)
mcpservers	MCP 服务	id, name, url, transport_type, is_enabled, tools_count

4.2 技能市场域

表名	说明
market_apps	市场应用（Skills/MCP/Agents）
market_app_versions	应用版本
app_purchases	购买记录
app_reviews	评价
app_installations	安装记录
skill_versions	技能版本
skill_publish_records	发布记录
evolution_skills	进��技能
evolution_events	进化事件
evolution_trajectories	进化轨迹
team_shared_skills	团队共享技能

4.3 知识库域

表名	说明
knowledge_bases	知识库
knowledge_directories	知识目录
knowledge_documents	文档
knowledge_document_chunks	文档分块
knowledge_graph_nodes	知识图谱节点
knowledge_graph_edges	知识图谱边
external_kb_services	外部 KB 服务

4.4 会员/支付域

表名	说明
membership_plans	会员计划
membership_subscriptions	订阅
orders	订单
coupons	优惠券
user_coupons	用户优惠券
value_added_services	增值服务
payment_configs	支付配置

4.5 监控/运维域

表名	说明
token_usage_logs	Token 用量日志
token_balances	余额
operation_logs	操作日志
audit_logs	审计日志
login_logs	登录日志
risk_rules	风控规则
slow_request_logs	慢请求日志
api_call_stats	API 调用统计
task_execution_logs	任务执行日志

五、API 全景

5.1 前台 API（用户面）

路由前缀	端点	方法	说明
/app/api/auth	/login	POST	用户登录，返回 JWT
/app/api/auth	/register	POST	注册
/app/api/chat	/conversations	GET/POST	对话列表/创建
/app/api/chat	/conversations/{id}/messages	POST	发送消息（非流式）
/app/api/chat	/conversations/{id}/messages/stream	POST	SSE 流式聊天
/app/api/chat	/models	GET	可用模型列表
/app/api/chat	/media/relay	GET	媒体代理
/app/api/market	/apps	GET	应用市场列表
/app/api/market	/apps/{id}	GET	应用详情
/app/api/knowledge	/search	POST	知识库搜索

5.2 后台 API（管理面）

路由前缀	说明
/app/api/admin/users	用户管理
/app/api/admin/models	模型管理
/app/api/admin/skills	技能管理
/app/api/admin/agents	Agent 管理
/app/api/admin/mcp	MCP 服务管理
/app/api/admin/workflow	工作流管理
/app/api/admin/market	市场管理
/app/api/admin/analytics	数据分析
/app/api/admin/developer	开发者 API
/app/api/admin/settings	站点设置
/app/api/admin/storage	存储管理
/app/api/admin/logs	日志查看
/app/api/admin/automation	自动化任务

5.3 SSE 事件类型

POST /conversations/{id}/messages/stream
Content-Type: text/event-stream

事件帧:
  data: {"type":"reasoning","content":"..."}   // 模型推理过程
  data: {"type":"delta","content":"..."}        // 逐字回复增量  
  data: {"type":"step","step":{...}}            // 工具调用步骤
    step.type: "thinking" | "skill" | "mcp"
  data: {"type":"done","message_id":"..."}      // 流结束

六、核心管道与工作流

6.1 消息处理管道（主循环）

用户消息
  → 鉴权（JWT Bearer）
  → 上下文恢复（skill_ids/agent_ids/mcp_ids 跨轮继承）
  → 技能解析（显式选择 → 自动发现 → Agent 合并）
  → MCP 工具列表拉取（带缓存 TTL 120s，按 url + transport 缓存）
  → 知识库检索（RAG，BM25 + vector hybrid）
  → System Prompt 组装（AGENT_GUIDE + platform_knowledge + agent_role + skill_desc + kb_context）
  → Function Definitions 组装（skills → tools + MCP → tools + install_app）
  → LLM 调用（OpenAI 兼容协议，stream=True）
  → Tool Calls 循环（max 15 轮，每轮 tool_policy 沙箱检查）
     ├── MCP Tool → call_mcp_tool() via Anthropic SDK
     ├── Skill → _execute_skill_tool() 指令转发
     └── install_app → 安装到市场
  → 工具结果回注 → 继续 LLM 循环 → 最终回复
  → 上下文压缩（后台异步，fire-and-forget）
  → 结构化记忆抽取（实体/事实/偏好/决策/待办 五类）
  → 媒体生成（后台 daemon 线程，独立事件循环）

6.2 模型路由与 Failover 管道

模型选择 → 解析 api_url/api_key/provider.auth_header
  → build_openai_client（httpx.Timeout + trust_env=False + auth_header 支持）
  → 首次调用失败（Exception）→ continue 下一个模型
  → 备用模型列表（order_by is_default desc × 5）
  → 成功 → break
  → 全部失败 → 返回错误消息

6.3 MCP 协议管道

Client: mcp_client.py (官方 Anthropic SDK)
  list_mcp_tools(server) → tools/list (JSON-RPC)
    ⇢ 缓存: _TOOLS_CACHE[url] = (timestamp, tools), TTL 120s
  call_mcp_tool(server, name, arguments) → tools/call (JSON-RPC)
    ⇢ 返回: text content blocks → 拼接为字符串 → 反馈给 LLM

传输层:
  streamable_http (默认) → streamablehttp_client()
  sse → sse_client()

Schema 适配:
  MCP inputSchema (JSON Schema 2020-12) → _normalize_mcp_schema()
    ⇢ 展开 $ref → 处理 oneOf/anyOf → allOf 合并 → 剥离非 OpenAI 关���字
    ⇢ 转为 OpenAI function calling 兼容的 parameters

认证:
  Authorization: Bearer {key} (默认)
  api-key: {key} (MiMo Token Plan 等自定义)

6.4 Agent 编排管道（DAG 图引擎）

YAML 定义 → validate_graph() → topological_layers() (Kahn算法)
  → 按层并行执行 (asyncio.gather)
  
节点类型:
  llm     → _build_system_prompt + LLM 调用
  local   → _execute_skill_tool (本地技能)
  external → _call_external_agent (Dify/n8n/Coze 远程)
  reduce  → 多路结果聚合

边: 有向边定义数据流 → 拓扑排序 → 分层并行
失败隔离: per-node on_error=halt|continue
并发安全: 每节点独立 SessionLocal()

预处理流水线:
  外部 Agent endpoint → 直接远程调用（跳过本地 LLM）
  Orchestrator → run_graph() → 图执行 → 聚合回答

6.5 媒体生成管道

SSE 回复结束 → _launch_media_task_bg()
  → daemon Thread → asyncio.run(_generate_media_task)
    → 独立事件循环（不阻塞主 uvicorn 循环）
    → HTTP 调用图片/视频生成 API
    → 写入存储 → 更新 Message 记录
    → 前端轮询 → 渲染结果

6.6 上下文压缩管道

(后台异步, fire-and-forget, 不阻塞用户响应)

旧消息 (>20 条保护窗口外)
  → 分块 (CHUNK=30) → _summarize_via_llm()
  → chunk_summaries 合并
  → _recursive_compress() (depth≤3, budget=700 tokens)
  → _extract_structured_memory()
    实体/事实/偏好/决策/待办 五类
  → _merge_structured_memory(old, new)
  → ConversationSummary 写入 PG

七、前端架构

7.1 路由设计

前台 (/):
  /login                      - 登录
  /chat[/:id]                 - AI 对话（核心页面，SSE 流式）
  /knowledge                  - 知识库管理
  /market                     - 应用市场（Skills/MCP/Agents）
  /token                      - Token 用量面板
  /pricing                    - 定价/会员
  /profile                    - 个人中心
  /assets[/novel/:id]         - 资产/小说
  /evolution                  - 进化仪表板
  /wechat-bot                 - 微信 Bot
  /im-bots                    - 多平台 IM Bot Hub
  /app-services               - 应用服务

后台 (/admin):
  /admin                      - 仪表板
  /admin/users                - 用户管理
  /admin/models               - 模型管理
  /admin/skills               - 技能管理
  /admin/agents               - Agent 管理
  /admin/mcp                  - MCP 管理
  /admin/workflow             - 工作流
  /admin/market               - 市场审核
  /admin/knowledge            - 知识库管理
  /admin/code-exec            - 代码执行
  /admin/storage              - 存储管理
  /admin/developer[/tools]    - 开发者 API/工具
  /admin/automation           - 自动化任务
  /admin/settings             - 站点设置
  /admin/analytics            - 数据分析
  /admin/logs                 - 日志
  /admin/membership           - 会员管理
  /admin/payment              - 支付配置
  /admin/services             - 增值服务
  /admin/ads                  - 广告管理
  /admin/apps                 - 应用管理

7.2 核心组件

组件	文件	功能
ChatPage	front/ChatPage.tsx	SSE 流式聊天、Step 渲染、推理展示
AiProcessBlock	ChatPage.tsx 内	工具调用过程可视化（⏳/✅/❌）
MarketPage	front/MarketPage.tsx	应用市场网格、分类筛选
FrontLayout	components/layout/FrontLayout.tsx	前台 sidebar + main 布局
AdminLayout	components/layout/AdminLayout.tsx	后台 sidebar + main 布局

7.3 设计系统

CSS 变量（global.css :root）:
  --color-accent: #5B5FED
  --color-bg-primary: #F8F9FB
  --sidebar-width: 240px
  --space-xs..4xl: 4px..40px
  --radius-md..3xl: 8px..20px

防溢出: html/body/.front-main { overflow-x: hidden }
响应式: @media (max-width: 1200px/768px) 断点

八、安全设计

8.1 认证

JWT Bearer Token 认证（FastAPI HTTPBearer）
Casdoor OAuth2/OIDC 统一认证（可选）
Token 前端存内存，401/403 清 token 跳 /login

8.2 授权

前台: 用户级（需登录）
后台: 管理员级（role=admin）
API Key: 支持 per-model key 覆盖 provider key

8.3 工具调用沙箱

_check_tool_policy() 三层防护:
  1. 白名单: agent 只允许调特定 skill_ids + mcp_ids
  2. 预算: max_calls_per_conversation 上限
  3. 每轮上限: per_round_cap

代码执行: 独立 executor 容器沙箱
密钥管理: credential.py 加解密存储

九、运维架构

9.1 CI/CD

Git push → pre-push hook (.git/hooks/pre-push)
  → 容器内 backend pytest (28 用例)
  → 容器内 frontend vitest (2 文件, 15 用例)
  → 全绿 → push 放行
  → 失败 → block

部署:
  docker cp 容器文件 → 宿主 Git
  → git add -A + commit
  → docker commit → qihuaiflow:with-deps (新镜像)
  → docker compose up -d --force-recreate

9.2 健康检查

/health          → 200 {status: "ok"}     (liveness)
前端 :8080       → 200 HTML               (SPA)
后端 :18080/docs → 200 Swagger UI
容器: docker restart → < 20s 恢复

9.3 监控栈

Prometheus (scrape) ← node-exporter (host) + Alloy (logs)
Grafana (visualize) ← Prometheus datasource
应用日志: Python logging → docker logs / Alloy 采集

十、市场竞争分析

10.1 护城河

护城河	具体实现	壁垒强度
多模型协议适配层	OpenAI/Anthropic/Token Plan 三种认证头、MCP Schema → OpenAI 转换	🔴 高
Skill 全生命周期	发布→审核→上架→安装→执行→进化，闭环	🔴 高
Agent DAG 编排	拓扑排序+分层并行+失败隔离+外部 Agent 远程调用	🟡 中
工具调��标准化	AGENT_GUIDE + tool_policy 沙箱 + 15 轮 loop + 错误自修正	🟡 中
PG 统一数据层	主库+向量+Casdoor 同集群 pgvector，混合检索零延迟	🟡 中
IM Bot 多平台	统一消息网关，微信/企业微信/飞书/QQ	🟢 低
安全沙箱	Tool Policy 白名单+预算+代码执行容器隔离	🟡 中

10.2 竞品对比

维度	七虎AI	Dify	Coze	扣子	FastGPT
模型聚合	✅ 手动 failover	✅	✅	✅	✅
Skill 市场	✅ 上架-安装-进化	❌	❌ (Plugin)	❌ (Plugin)	❌
MCP 协议	✅ 官方 SDK	✅	❌	❌	❌
Agent DAG	✅ 图引擎	✅ 工作流	✅ 工作流	✅ 工作流	❌ 简单
IM Bot	✅ 多平台	❌	❌	✅ 飞书	❌
PG 全栈	✅ PG18	⚠️ MySQL	?	?	✅ PG
Auth	✅ Casdoor+JWT	✅	✅	✅	✅

10.3 扩展能力

扩展方向	当前能力	增长空间
模型厂商	4 家	新增厂商只需配 ModelProvider
Skill 类型	14 场景分类	支持自定义执行器（非纯 LLM 转发）
MCP 服务	任意 MCP Server	MCP Registry 对接
Agent	Dify/n8n/Coze + 自研 DAG	CrewAI/LangGraph 集成
前端渠道	Web Chat + IM Bot	API/Webhook/SDK
计费	Token + 会员	按 Skill/MCP 调用计费

十一、迭代路线图

已完成

PostgreSQL 迁移（MySQL → PG18 + pgvector）
SSE 四类事件（reasoning/delta/step/done）
MCP 协议标准化（官方 SDK，Schema 转换）
Agent DAG 编排引擎 + YAML workflow
工具调用标准化（AGENT_GUIDE + install_app 优化 + max_rounds 15 + MCP 命名）
模型 Failover + 事件循环防冻（#812）
Token Plan 适配（MiMo custom auth_header）
前端 Step 渲染增强（⏳/✅/❌ 状态）
横向溢出防护（overflow-x: hidden 三层）
知识库 KG 构建
多平台 IM Bot Hub
Prometheus+Grafana 监控栈

进行中

Skill 真实执行器（非 LLM 转发模拟）
多 Agent 协作（Supervisor 模式）
API/OpenAPI 对外接口
技能 SDK 发布工具

计划中

LiteLLM 集成（统一模型路由+成本追踪）
流式 Token 计费（精确到字符级）
LangGraph 工作流引擎
向量混合检索增强（BM25 + dense + sparse）
前端暗色模式
多语言（i18n）
移动端适配

文档维护规则: 每次系统重大迭代后，更新本文档对应章节并变更版本号。 上传位置: Gitea 仓库 qihuaiflow/docs/ARCHITECTURE.md

19 KiB Raw Blame History Unescape Escape