AIFlowy 接口简介

1. 背景与愿景：从“对话”到“集成”

在 2024-2025 年，大多数企业对 AI 的尝试停留在“聊天机器人”或“单次问答”的体验阶段。然而，进入 2026 年，随着 AIFlowy 等智能体中台的成熟，企业需求发生了根本性转变：

不再是：“我想和一个 AI 聊聊天。”

而是：“我需要将 AI 的思考能力、执行能力和知识能力，无缝嵌入到我的 ERP、CRM、OA 以及自研业务系统中。”

AIFlowy API 正是为此而生。它不仅仅是一组 HTTP 接口，它是 AIFlowy 智能体中台能力的标准化输出通道。通过这套 API，开发者可以将 AIFlowy 视为一个巨大的、可编排的“AI 操作系统”，通过代码调用其核心模块，实现业务流程的自动化、智能化升级。

作为 Agents-Flex 的作者和 Java AI 生态的推动者，我在设计 AIFlowy API 时，严格遵循了 “真开源 · 易集成 · 生产就绪” 的原则，确保每一行代码、每一个接口都具备企业级的稳定性、安全性和可扩展性。

2. AIFlowy API 核心架构概览

AIFlowy API 采用 RESTful 风格，基于 HTTPS 协议，通过 API Key 进行身份认证。整体架构分为五大层级：

交互层 (Interaction Layer)：智能体 (Bot)、工作流 (Workflow)。

知识层 (Knowledge Layer)：知识库 RAG、Wiki 知识树、素材库。

数据层 (Data Layer)：数据中枢 (Smart Query)、向量数据库、数据集。

扩展层 (Extension Layer)：插件 (Plugins)、MCP (Model Context Protocol)。

治理层 (Governance Layer)：模型管理、安全合规、日志分析、反馈闭环。

3. 详细模块详解

3.1 智能体与工作流引擎 (The Brain & The Hands)

这是 AIFlowy 的核心执行单元，负责处理复杂的逻辑推理和任务执行。

智能体 API (Bot API)

智能体是拥有特定人设、记忆和工具使用权的 AI 实体。

核心能力：

多轮对话上下文管理：自动维护会话状态，支持长短期记忆切换。

动态工具调用：根据用户意图，自动选择并调用绑定的插件或 MCP 服务。

RAG 增强：自动检索相关知识库，生成基于事实的回答。

典型接口：

POST /api/v1/bots/{botId}/chat：发起同步对话。

POST /api/v1/bots/{botId}/chat/stream：发起流式对话（SSE），适用于前端打字机效果。

GET /api/v1/bots/{botId}/sessions/{sessionId}：获取指定会话的历史记录和上下文摘要。

应用场景：

嵌入企业官网的 7x24 小时智能客服。

集成在 CRM 中的 销售助手，自动分析客户画像并推荐话术。

工作流 API (Workflow API)

工作流是将复杂任务拆解为多个步骤（节点）并串联执行的引擎。相比单一 Bot，Workflow 更适合确定性高、流程长的业务场景。

核心能力：

可视化编排执行：支持串行、并行、条件分支、循环等复杂逻辑。

变量传递：节点间通过上下文变量传递数据。

人工介入节点：支持在流程中暂停，等待人工审核或输入。

典型接口：

POST /api/v1/workflows/{workflowId}/execute：触发工作流执行，传入初始参数（JSON）。

GET /api/v1/workflows/executions/{executionId}/status：查询长耗时任务的执行状态。

POST /api/v1/workflows/executions/{executionId}/resume：在人工审核节点后，提交审核结果以恢复流程。

应用场景：

自动化研报生成：抓取新闻 -> 总结要点 -> 生成图表 -> 撰写报告 -> 发送邮件。

智能合同审核：OCR 识别合同 -> 提取关键条款 -> 比对合规库 -> 生成风险报告。

3.2 知识管理与 RAG 引擎 (The Memory)

让 AI 懂业务、懂内部数据的关键。AIFlowy 提供了两种形态的知识管理：非结构化文档 RAG 和 结构化 Wiki 知识树。

知识库 RAG API

核心能力：

多格式解析：支持 PDF, Word, Excel, PPT, Markdown, TXT 等格式的高精度解析。

智能分块 (Chunking)：基于语义而非固定字符数的智能切片，保留上下文完整性。

混合检索 (Hybrid Search)：结合关键词检索 (BM25) 和向量检索 (Vector)，提高召回率。

重排 (Rerank)：使用专用重排模型对召回片段进行相关性排序，提升最终回答质量。

典型接口：

POST /api/v1/knowledge-base/{kbId}/documents：上传文档并触发异步解析索引。

POST /api/v1/knowledge-base/{kbId}/search：执行语义检索，返回相关片段及相似度得分。

DELETE /api/v1/knowledge-base/{kbId}/documents/{docId}：删除文档并清理向量索引。

应用场景：

企业内部知识问答：员工询问“报销流程”，AI 基于最新制度文档回答。

技术支持助手：基于产品手册和故障案例库，辅助技术人员排查问题。

Wiki 知识树 API

传统 RAG 适合碎片化知识，而 Wiki 知识树 适合结构化、层级化的知识体系。

核心优势：

结构化存储：知识以树状节点存在，每个节点包含标题、内容、关联标签。

关系感知：AI 理解知识的上下级关系（如：产品 -> 模块 -> 功能 -> 参数）。

长期记忆载体：适合作为 AI 的“长期记忆库”，存储经过验证的高质量知识。

典型接口：

POST /api/v1/wiki/nodes：创建新的知识节点。

PUT /api/v1/wiki/nodes/{nodeId}：更新节点内容或结构。

GET /api/v1/wiki/nodes/{nodeId}/path：获取节点的完整路径，用于构建面包屑导航或上下文注入。

应用场景：

产品文档中心：构建可交互的产品说明书，AI 可沿树状结构深入讲解。

行业专家系统：将行业标准、法规以树状结构沉淀，确保 AI 回答的逻辑严密性。

3.3 数据智能与向量底座 (The Data Foundation)

数据中枢 API (Smart Query)

让非技术人员也能通过自然语言查询数据库。

核心能力：

Text-to-SQL：基于 Schema 信息，将自然语言转换为可执行 SQL。

多数据源支持：MySQL, PostgreSQL, Oracle, ClickHouse, Elasticsearch 等。

安全沙箱：只读权限控制，防止误删改；敏感字段自动脱敏。

图表推荐：根据数据类型自动推荐合适的可视化图表（折线图、柱状图等）。

典型接口：

POST /api/v1/data-center/query：输入自然语言问题，返回 SQL、执行结果及图表配置。

GET /api/v1/data-center/datasources：列出已配置的数据源及其 Schema 摘要。

应用场景：

BI 自助分析：运营人员问“上周各地区的销售额对比”，直接生成报表。

实时监控大屏：通过 API 定时查询关键指标，驱动前端大屏更新。

向量数据库 API

AIFlowy 内置高性能向量存储，也可对接外部向量库。

核心能力：

向量 CRUD：标准的增删改查操作。

元数据过滤 (Metadata Filtering)：在向量检索的同时，支持基于标签、时间、用户ID等字段的精确过滤。

多租户隔离：基于 Namespace 或 Collection 实现数据隔离。

典型接口：

POST /api/v1/vectors/upsert：批量写入向量及元数据。

POST /api/v1/vectors/query：执行相似性搜索，支持 Top-K 和阈值过滤。

应用场景：

以图搜图/以文搜图：结合 Embedding 模型，实现多媒体内容的语义检索。

个性化推荐：基于用户历史行为的向量表示，召回相似内容。

3.4 扩展生态：插件与 MCP (The Extensions)

打破 AI 的信息孤岛，连接外部世界。

插件 API (Plugins)

核心能力：

OpenAPI 兼容：支持导入 Swagger/OpenAPI 规范自动生成插件。

自定义鉴权：支持 API Key, OAuth2, Basic Auth 等多种鉴权方式。

参数映射：灵活配置 LLM 输出到插件输入参数的映射规则。

典型接口：

POST /api/v1/plugins/invoke：手动触发插件执行，用于测试或特定业务逻辑。

GET /api/v1/plugins/catalog：获取可用插件列表及描述。

应用场景：

天气查询：AI 调用天气插件回答“明天北京天气如何”。

Jira/钉钉集成：AI 自动创建任务票或发送通知消息。

MCP (Model Context Protocol) API

AIFlowy 是 MCP 协议的坚定支持者，旨在实现 AI 与本地/远程工具的标准化互联。

核心能力：

MCP Server 管理：注册、发现、监控 MCP 服务器状态。

工具动态加载：运行时动态加载 MCP 提供的 Tools, Resources, Prompts。

MCP 商店集成：一键安装社区发布的 MCP 服务。

典型接口：

POST /api/v1/mcp/servers/register：注册一个新的 MCP Server。

GET /api/v1/mcp/tools：列出所有已连接的 MCP 工具及其 Schema。

应用场景：

IDE 集成：通过 MCP 连接本地文件系统，让 AI 辅助编写代码。

浏览器自动化：连接 Browser MCP，让 AI 能够浏览网页、提取信息。

3.5 模型管理与基础设施 (The Infrastructure)

模型管理 API

核心能力：

多模型路由：根据任务类型（聊天、编码、数学）自动路由到最佳模型。

负载均衡与降级：当主模型超时或错误时，自动切换到备用模型。

统一计费与配额：统计各模型的 Token 消耗，支持租户级配额限制。

支持模型类型：

Chat Models (Qwen, DeepSeek, Claude, GPT-4o...)

Embedding Models (BGE, M3E...)

Rerank Models (BGE-Reranker...)

OCR Models (PaddleOCR, Tesseract...)

典型接口：

POST /api/v1/models/chat/completions：直接调用底层模型（绕过 Agent 逻辑）。

GET /api/v1/models/status：检查各模型提供商的健康状态。

3.6 数据闭环与安全治理 (The Governance)

企业级应用的核心壁垒：安全与进化。

安全与合规 API

敏感词库：

POST /api/v1/security/check：预检文本，识别政治、暴力、色情等敏感内容。

支持自定义词库导入，满足行业合规要求（如金融、医疗）。

预警管理：

实时监控 API 调用异常、Token 消耗激增、潜在的攻击行为（Prompt Injection）。

支持 Webhook 回调告警。

对话分析与反馈闭环

用户反馈 (Feedback)：

POST /api/v1/feedback：提交点赞/点踩及原因。

自动化标注：点踩数据自动进入“待标注队列”，结合人工修正，形成高质量 SFT 数据集。

深度洞察 (Insights)：

GET /api/v1/analytics/conversations/{id}：获取单次对话的深度分析报告，包括：

用户核心诉求：AI 提炼的用户真实意图。

用户画像推测：基于对话内容推测的职业、兴趣、专业程度。

情感分析：用户情绪变化曲线。

价值：帮助产品经理优化 Bot 人设，帮助销售人员洞察客户潜在需求。

4. 接入指南与技术规范

4.1 认证机制

所有 API 请求必须在 Header 中包含 API Key：

安全性：API Key 具有权限 scope（如只读、读写、管理员），建议最小权限原则。

限流：默认限制每秒请求数 (QPS)，可在控制台申请提升配额。

4.2 响应格式

统一 JSON 响应结构：

{
  "code": 200,
  "message": "success",
  "data": { ... },
  "meta": {
    "requestId": "req_1234567890",
    "timestamp": 1715600000000
  }
}

错误处理：非 200 状态码时，data 为空，message 包含错误详情，code 为具体错误码（如 40101 代表 Key 无效）。

4.3 最佳实践

异步处理长任务：对于文档解析、工作流执行等耗时操作，建议使用 async 模式，通过 executionId 轮询状态或配置 Webhook 回调。

流式响应体验：前端聊天场景务必使用 /stream 接口，提升用户首字等待体验 (TTFT)。

上下文精简：在调用 Bot API 时，可通过参数控制携带的历史消息条数，避免 Token 浪费。

日志脱敏：AIFlowy 服务端会自动对日志中的敏感字段（如手机号、身份证）进行脱敏，但建议在客户端也做好数据最小化传输。

5. 典型集成案例

案例一：Java 后端集成智能客服

使用 SpringBoot + RestTemplate/OkHttp 调用 AIFlowy Bot API。

案例二：自动化周报生成工作流

触发：每周五下午 5 点，cron 任务调用 POST /workflows/weekly-report/execute。

输入： { "userId": "emp_001", "weekStart": "2026-05-04", "weekEnd": "2026-05-08" }

执行：

节点1：调用 Jira Plugin 获取本周完成的任务。

节点2：调用 Git Plugin 获取代码提交记录。

节点3：LLM 节点汇总信息，生成周报草稿。

节点4：人工审核节点（暂停）。

节点5：邮件 Plugin 发送最终周报。

结果：员工只需在收到审核通知时确认即可，大幅减少重复劳动。

6. 结语：共建 Java AI 生态

AIFlowy API 的推出，是我们推动 Java AI 生态标准化 的重要一步。我们希望通过开放、稳定、高效的接口，降低企业使用 AI 的门槛，让每一位 Java 开发者都能轻松构建出具备“感知、思考、行动”能力的智能应用。

未来，我们将持续迭代：

更深度的 MCP 生态集成。

更强大的 多模态处理能力（视频、音频）。

更完善的 私有化部署方案。

欢迎加入 AIFlowy 开发者社区，一起探索 AI 原生应用的无限可能。

1. 背景与愿景：从“对话”到“集成”#

2. AIFlowy API 核心架构概览#

3. 详细模块详解#

3.1 智能体与工作流引擎 (The Brain & The Hands)#

智能体 API (Bot API)#

工作流 API (Workflow API)#

3.2 知识管理与 RAG 引擎 (The Memory)#

知识库 RAG API#

Wiki 知识树 API#

3.3 数据智能与向量底座 (The Data Foundation)#

数据中枢 API (Smart Query)#

向量数据库 API#

3.4 扩展生态：插件与 MCP (The Extensions)#

插件 API (Plugins)#

MCP (Model Context Protocol) API#

3.5 模型管理与基础设施 (The Infrastructure)#

模型管理 API#

3.6 数据闭环与安全治理 (The Governance)#

安全与合规 API#

对话分析与反馈闭环#

4. 接入指南与技术规范#

4.1 认证机制#

4.2 响应格式#

4.3 最佳实践#

5. 典型集成案例#

案例一：Java 后端集成智能客服#

案例二：自动化周报生成工作流#

6. 结语：共建 Java AI 生态#

1. 背景与愿景：从“对话”到“集成”

2. AIFlowy API 核心架构概览

3. 详细模块详解

3.1 智能体与工作流引擎 (The Brain & The Hands)

智能体 API (Bot API)

工作流 API (Workflow API)

3.2 知识管理与 RAG 引擎 (The Memory)

知识库 RAG API

Wiki 知识树 API

3.3 数据智能与向量底座 (The Data Foundation)

数据中枢 API (Smart Query)

向量数据库 API

3.4 扩展生态：插件与 MCP (The Extensions)

插件 API (Plugins)

MCP (Model Context Protocol) API

3.5 模型管理与基础设施 (The Infrastructure)

模型管理 API

3.6 数据闭环与安全治理 (The Governance)

安全与合规 API

对话分析与反馈闭环

4. 接入指南与技术规范

4.1 认证机制

4.2 响应格式

4.3 最佳实践

5. 典型集成案例

案例一：Java 后端集成智能客服

案例二：自动化周报生成工作流

6. 结语：共建 Java AI 生态