Flowise AI 对话集成指南

本文档介绍如何配置 Flowise 与 KKMusic 系统的集成，为用户提供 AI 对话助手功能。

一、概述

Flowise 是一个低代码 AI 工作流构建工具，KKMusic 通过 Flowise 提供：

AI 项目助手 - 回答项目规划、内容创作相关问题
智能推荐 - 基于项目数据提供个性化建议
知识问答 - 基于语料库的 RAG 问答

二、前置要求

Flowise 实例（本地或云端），推荐版本 1.4+
至少一个 LLM 模型（OpenAI/Claude/本地模型）
网络可达（后端能访问 Flowise API）

Flowise 部署方式

bash

# Docker 部署（推荐）
docker run -d \
  --name flowise \
  -p 3000:3000 \
  -v flowise_data:/root/.flowise \
  flowiseai/flowise

# 或使用 npm
npm install -g flowise
npx flowise start

⚠️ 注意：Flowise 默认端口 3000 与前端开发服务器冲突，建议改为其他端口

bash

# 使用其他端口
docker run -d -p 3030:3000 flowiseai/flowise

三、环境变量配置

在 backend/.env 中添加：

bash

# Flowise API 配置
FLOWISE_API_URL=http://localhost:3030/api/v1
FLOWISE_CHATFLOW_ID=your-chatflow-uuid
FLOWISE_API_KEY=your-api-key-if-enabled
FLOWISE_TIMEOUT=30000

四、创建 Chatflow

4.1 基础对话流

登录 Flowise 管理界面
点击 Create New Chatflow
添加以下节点：

[ChatOpenAI/ChatAnthropic] 
        ↓
[ConversationChain] 
        ↓
    [Output]

4.2 带知识库的对话流（推荐）

[Documents] → [Text Splitter] → [Embeddings] → [Vector Store]
                                                    ↓
[ChatModel] → [Conversational Retrieval QA Chain] ← ↑
                        ↓
                    [Output]

节点配置：

节点	配置
ChatOpenAI	model: gpt-4, temperature: 0.7
Text Splitter	chunkSize: 1000, chunkOverlap: 200
Embeddings	OpenAI Embeddings 或 HuggingFace
Vector Store	Pinecone / Chroma / In-Memory

4.3 系统提示词

在 ChatModel 节点中配置 System Message：

markdown

你是 KKMusic 的 AI 项目助手，专门帮助用户进行短视频内容创作和项目管理。

你的能力包括：
1. 回答关于内容创作、发布策略的问题
2. 根据用户项目情况提供建议
3. 解释系统功能和操作方法
4. 分析账号数据并给出优化建议

请注意：
- 回答要简洁实用，不要过于冗长
- 使用中文回答
- 如果不确定，诚实说明
- 适当使用表情符号增加亲和力

当前用户上下文：
- 项目ID: {projectId}
- 用户名: {username}

五、获取 Chatflow ID

创建并保存 Chatflow 后
点击右上角 API 按钮
复制 Chatflow ID（UUID 格式）
填入环境变量 FLOWISE_CHATFLOW_ID

六、API 调用流程

KKMusic 后端通过 FlowiseProxyService 与 Flowise 交互：

前端 → /api/ai/chat → FlowiseProxyService → Flowise API → LLM
                            ↓
                    会话管理 + 上下文注入

主要 API 端点

端点	方法	说明
`/api/ai/chat`	POST	发送消息
`/api/ai/chat/history/:sessionId`	GET	获取历史
`/api/ai/chat/session/:sessionId`	DELETE	清除会话
`/api/ai/chat/health`	GET	健康检查

请求示例

bash

curl -X POST http://localhost:3001/api/ai/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-jwt-token" \
  -d '{
    "message": "我这周应该发什么内容？",
    "sessionId": "optional-session-id",
    "context": {
      "projectId": "project-123"
    }
  }'

响应示例

json

{
  "success": true,
  "sessionId": "uuid-xxx",
  "response": "根据您的项目数据，建议本周发布以下内容：\n1. 周一：店铺环境展示\n2. 周三：产品特写\n...",
  "sources": []
}

七、上下文注入

自动注入的上下文

当用户发起对话时，系统自动注入：

userId - 用户 ID
username - 用户名
projectId - 当前项目 ID
projectContext - 项目摘要信息
chatHistory - 最近对话历史

自定义上下文

在前端调用时传入：

javascript

await api.post('/api/ai/chat', {
  message: '帮我分析这个月的数据',
  context: {
    projectId: currentProject.id,
    projectInfo: {
      name: currentProject.name,
      type: currentProject.type,
      industry: currentProject.industry
    },
    customData: {
      monthlyStats: monthlyStats
    }
  }
})

八、降级处理

当 Flowise 不可用时，系统提供降级响应：

javascript

// 返回示例
{
  "success": false,
  "fallback": true,
  "response": "抱歉，AI 助手暂时不可用。您可以在「项目控制台」中查看和管理您的内容计划..."
}

降级响应根据用户问题关键词提供基础指引。

九、安全配置

启用 API Key

在 Flowise 设置中启用 API Key
生成 API Key
配置到环境变量 FLOWISE_API_KEY

请求限流

后端已集成速率限制，防止滥用：

javascript

// 默认限制：每分钟 30 次
app.use('/api/ai', apiLimiter, aiChatRoutes);

十、进阶配置

10.1 对接项目数据

在 Flowise 中使用 HTTP Request 节点获取项目数据：

GET http://localhost:3001/api/projects/:id
Authorization: Bearer {internal_token}

10.2 对接语料库

使用 Retrieval QA 节点，配置：

API Endpoint: http://localhost:3001/api/corpus
Method: GET
Query: project_id={projectId}

10.3 自定义工具

Flowise 支持自定义工具，可创建：

查询任务进度工具
创建内容工具
发布内容工具

十一、故障排查

常见问题

连接失败
- 检查 FLOWISE_API_URL 地址
- 确认 Flowise 服务运行中
- 检查端口是否被占用
响应超时
- 增加 FLOWISE_TIMEOUT 值
- 检查 LLM 模型响应速度
- 考虑使用更快的模型
Chatflow ID 无效
- 确认 Chatflow 已保存并发布
- 重新获取 Chatflow ID

日志查看

bash

# 后端日志
grep "FlowiseProxy" backend.log

# 健康检查
curl http://localhost:3001/api/ai/chat/health

十二、最佳实践

会话管理
- 定期清理过期会话
- 使用 Redis 存储会话（生产环境）
提示词优化
- 根据实际场景调整系统提示词
- 收集用户反馈持续优化
知识库更新
- 定期更新语料库
- 同步最新的产品文档
监控告警
- 监控 Flowise 服务状态
- 设置响应时间告警

Flowise AI 对话集成指南 ​

一、概述 ​

二、前置要求 ​

Flowise 部署方式 ​

三、环境变量配置 ​

四、创建 Chatflow ​

4.1 基础对话流 ​

4.2 带知识库的对话流（推荐） ​

4.3 系统提示词 ​

五、获取 Chatflow ID ​

六、API 调用流程 ​

主要 API 端点 ​

请求示例 ​

响应示例 ​

七、上下文注入 ​

自动注入的上下文 ​

自定义上下文 ​

八、降级处理 ​

九、安全配置 ​

启用 API Key ​

请求限流 ​

十、进阶配置 ​

10.1 对接项目数据 ​

10.2 对接语料库 ​

10.3 自定义工具 ​

十一、故障排查 ​

常见问题 ​

日志查看 ​

十二、最佳实践 ​

十三、相关资源 ​

Flowise AI 对话集成指南

一、概述

二、前置要求

Flowise 部署方式

三、环境变量配置

四、创建 Chatflow

4.1 基础对话流

4.2 带知识库的对话流（推荐）

4.3 系统提示词

五、获取 Chatflow ID

六、API 调用流程

主要 API 端点

请求示例

响应示例

七、上下文注入

自动注入的上下文

自定义上下文

八、降级处理

九、安全配置

启用 API Key

请求限流

十、进阶配置

10.1 对接项目数据

10.2 对接语料库

10.3 自定义工具

十一、故障排查

常见问题

日志查看

十二、最佳实践

十三、相关资源