大模型管理与智能客服 · 完整使用与配置文档

适用对象：GFast V4 后台管理员、二次开发者
对应模块：后台「大模型管理」「智能客服」

目录

1. 模块总览
2. 大模型管理
3. MCP 服务器配置
4. AI 对话
5. 智能客服（知识库 RAG）
6. 流程编排（SOP Workflow）
7. C 端开放接口与网站挂载插件
8. 权限与数据库要点
9. 常见问题与排错

一、模块总览

链路关系：知识库 = 知识 + 向量化模型 + 对话模型；文档喂给知识库 → Qdrant 向量化；客服对话用「检索 + 大模型」回答；流程编排把上述能力编排成 SOP。

二、大模型管理

2.1 模型接入协议（5 种）

通过数据库 lm_config.model_class 区分（值与字典 lm_protocol 一致）：

2.2 提供商预设（12 项）

lm_config.provider 用于前端预设与 baseUrl 缺省回退（字典 lm_provider）：

openai、bailian（百炼）、zhipu（智谱）、kimi（月之暗面）、hunyuan（腾讯混元）、minimax、mimo、ark（火山方舟）、deepseek、anthropic、ollama、custom（自定义）

内建默认 baseUrl：

baseUrl 回退顺序（重要）：显式填写的 base_url > 提供商预设 > 协议默认 > 组件默认。选「厂商」会自动填协议 + baseUrl，通常无需手填。

2.3 模型类型

2.4 配置字段说明

2.5 典型配置示例

对话模型：
  提供商 = 阿里百炼(bailian) / 火山方舟(ark)
  协议   = qwen（百炼）或 openai_compatible（方舟）
  模型名 = qwen3.8-flash / glm-5.3-flash（方舟）
  温度   = 0.7

向量模型（TextEmbedding，客服必配）：
  提供商 = bailian，协议 = qwen
  模型名 = text-embedding-v4（百炼，输出 1024 维）
  base_url = 留空（默认走 dashscope 官方端点）

三、MCP 服务器配置

MCP（Model Context Protocol）让大模型能调用外部工具（查天气、查订单、建工单等）。

• 入口：大模型管理 → mcp服务器配置列表（/llm/mcp）
• 关键字段：服务器名称、SSE 地址（如 http://服务端/mcp，需服务端实现 SSE 端点）
• 保存后，AI 对话发送时会自动拉取该服务器暴露的工具列表，模型按需调用

备注：MCP 工具的能力也可复用到「智能客服流程编排」的 LLM 节点（见 6.4）。

四、AI 对话

4.1 使用方式

• 选择模型（下拉：左侧模型名、右侧提供商小徽章）
• 输入问题 → 发送。采用真流式打字：WebSocket chat 事件逐字推送正文，chatThink 事件推送思考过程
• 历史消息通过 lm_chat_list / lm_chat_message 持久化

4.2 关键交互

五、智能客服（知识库 RAG）

基于「检索增强生成」：上传文档 → 切分 → 向量化入 Qdrant → 问答时检索最相关内容 + 大模型生成，回答标注引用来源。

5.1 前置条件（重要）

1. Qdrant 向量库可用：配置 manifest/config/config.yaml

   kb:
     qdrant:
       address: "http://192.168.0.214"   # Qdrant HTTP 地址
       grpcPort: 6334                    # Qdrant gRPC 端口
       apiKey: ""                        # 可选

   • 若 address 为空，知识库功能不可用
   • go-client 与 Qdrant 服务端版本必须匹配（主版本一致、次版本差 ≤1），否则向量「假写入」（Upsert 返回成功但实际 0 点），本机 go-client 升级后请同步升级 Qdrant 至 1.19.x

     安装qdrant

     创建一个qdrant数据库目录，进入该目录，创建docker-compose.yml,填入以下内容：

     services:
     qdrant:
     # 使用 2026 年最新稳定版本
     image: qdrant/qdrant:v1.19.0
     container_name: qdrant
     ports:
      - "6333:6333"  # REST API & Web UI
      - "6334:6334"  # gRPC API
     volumes:
      - ./qdrant_storage:/qdrant/storage
     environment:
      # 关闭遥测（可选，内网/隐私环境推荐）
      - QDRANT__TELEMETRY_DISABLED=true
     restart: unless-stopped
     # 限制资源，防止未来数据量大时 OOM
     deploy:
      resources:
        limits:
        # 注意我这里是测试环境，根据您实际情况处理，下同
          memory: 4G
        reservations:
          memory: 2G

     执行以下命令，Docker 会自动拉取最新的 v1.19.0 镜像并启动：
     docker compose up -d
     查看容器状态，确保状态为 Up
     docker compose ps
     打开浏览器，访问 Qdrant 的可视化面板：
     👉 http://localhost:6333/dashboard

2. TextEmbedding 模型：在大模型配置列表新增一条 TextEmbedding 类型配置（如百炼 text-embedding-v4），知识库创建时选择它

3. 对话模型：至少一条启用状态的 LLM 配置

5.2 知识库管理

每个知识库对应 Qdrant 一个独立 collection（命名 kb_{id}，Cosine 距离）。

5.3 文档管理

• 支持格式：txt / md / pdf / docx / xlsx / html（共 6 种）
• 处理流程：上传 → 异步 解析 → 分块 → 向量化 → 写入 Qdrant + 落库分块元数据（kb_chunk）
• 状态：0 待处理 / 1 处理中 / 2 完成 / 3 失败
• 处理失败可点「重试」；点文档可查看分块列表、查看向量入库后的引用结果

5.4 客服对话（后台）

• 三栏布局：会话列表 / 消息区 / 引用来源列表
• 发送时先检索知识库（topK 条），后台 WebSocket 流式推送，回答中用 [n] 标注引用，右侧来源卡联动高亮
• 顶部可选「执行流程」（见第六章），选择后走流程引擎而非直接 RAG

六、流程编排（SOP Workflow）

让客服按预设「标准作业程序」处理多步骤任务：意图识别 → 条件判断 → 路由 → 查询/转人工 → 回复。

核心技术：DSL（JSON）→ 后端用 eino compose.Graph 动态构建执行引擎；前端用 vue-flow 可视化画布编辑 DSL。

6.1 节点类型

内置插值变量：{{question}}（本次问题）、{{history}}（历史对话）、{{kbContext}}（检索资料）、{{kbSources}} 及 LLM 节点提取出的自定义变量。

分支表达式示例（expr 语法，基于上下文变量）：

intent == "投诉"
confidence < 0.5
（留空 = 默认分支）

6.2 画布操作

• 添加节点：点击左侧「节点库」卡片
• 连线：鼠标移到节点 → 节点左右出现蓝色圆点锚点 → 从右侧「出锚点」按住拖到目标节点左侧「入锚点」松开
  • 普通节点只有一条出线（重复连会替换）
  • 条件分支节点每个分支对应一个独立出线锚点，从哪条分支行拖出代表哪条路由；连线上自动显示分支条件标签（空条件显示「默认」），改条件实时同步
• 删除连线：单击选中连线（高亮）→ 按 Backspace 或 Delete
• 删除节点：选中后按 Delete/Backspace，或「删除选中」按钮（开始节点受保护）
• 防呆规则：branch→branch 禁止、branch 仅一条入边、连线实时防环、保存时全量校验（开始唯一/有结束/分支已连线/无环）

6.3 测试运行

• 画布「测试运行」或列表页「测试」按钮：输入测试问题 → 返回逐节点轨迹（类型/耗时/摘要）+ 最终回复 + 变量快照 + 是否转人工
• 正式客服对话走流程时，执行轨迹可查后端日志（kbFlow trace flowId/sessionId/...）用于排错

6.4 流程与其它能力组合

• 流程可挂到「应用管理」的应用上（见第七章），C 端问答自动走流程
• LLM 节点配置 MCP 服务器后即可在流程内调用业务工具
• 转人工消息落库带 [[HANDOFF]] 前缀，前端渲染为橙色「已转人工」标签

七、C 端开放接口与网站挂载插件

7.1 应用管理与凭证

• 入口：智能客服 → 应用管理
• 新建应用：绑定知识库、可绑定流程（选后 C 端问答走流程）、分配 appKey + appSecret
• 状态开关：停用后 C 端接口立即失效（安全兜底）
• 表格显示绑定知识库/流程；接口弹窗含 curl 示例与网站挂载代码

7.2 接口一：服务器对服务器（全凭证）

POST /api/v1/kb/open/chat

{
  "appKey": "kb-xxxxxxxx",
  "appSecret": "xxxxxxxx",
  "kbId": 1,
  "sessionId": "",
  "visitorId": "visitor-001",
  "question": "如何修改检索条数？"
}

返回 SSE 事件流：

• 校验：appKey + appSecret + 知识库归属 + 按 appKey 秒级滑窗限流（10 QPS，常量 KbOpenRateLimitQps）
• 鉴权方式：请求体携带（生产环境请用 HTTPS）

7.3 接口二：网站挂载（仅 appKey）

插件脚本部署在网页中，appSecret 会泄露，故提供仅 appKey 的公开入口，安全性靠：启用开关 + 知识库绑定校验 + 限流。

POST /api/v1/kb/open/widget/chat

{ "appKey": "kb-xxxxxxxx", "kbId": 1, "sessionId": "", "visitorId": "xxx", "question": "..." }

仅校验 appKey 存在/启用 + 知识库归属 + 限流，SSE 事件同上。

7.4 网站挂载插件（kb-widget.js）

单文件、零依赖、后端静态托管（/kb-widget/kb-widget.js）。目标网站 body 内加一行：

<script src="http://你的gfast地址/kb-widget/kb-widget.js"
        data-app-key="kb-xxxxxxxx"
        data-kb-id="1"
        data-title="在线客服"
        data-primary="#4f7cff"
        defer></script>

• 右下角悬浮气泡 → 点击展开聊天面板（Shadow DOM，与宿主样式完全隔离）
• 流式打字、思考过程折叠、引用来源卡片、多轮会话续聊
• data-server 缺省自动取脚本来源域名；visitorId（localStorage 持久）、sessionId（sessionStorage 续聊）
• 演示页：http://你的地址/kb-widget/demo.html
• 安全提醒：appKey 为公开凭证，敏感知识库请勿挂载到公开站点

八、权限与数据库要点

8.1 菜单与会话

• 无需验证权限的后台用户 id：system.notCheckAuthAdminIds: [1,2,31]（含 admin）
• 其它角色需在「角色管理」分配对应菜单；智能客服子菜单（知识库/文档/客服对话/流程编排/应用管理）与各按钮权限在菜单管理配置
• 修改 casbin_rule 后需重启后端（enforcer 内存缓存）

8.2 核心数据表

九、常见问题与排错