Skip to content

creattt840/Hify

BranchesTags

Repository files navigation

Hify

简版 AI Agent 开发平台，本地部署，面向 20–50 人团队内部使用。

技术栈

层级 技术
后端 Spring Boot 3.3、MyBatis-Plus、MySQL 8.x、Redis 7.x
向量库 PostgreSQL 18 + pgvector（知识库分块与 Embedding 存储）
前端 Vue 3、TypeScript、Vite、Element Plus、Vue Flow（工作流可视化编辑）
工具协议 MCP（Model Context Protocol），支持 Streamable HTTP / SSE 传输

功能概览

  • 模型管理：配置 OpenAI / Anthropic / Gemini / Ollama 及 OpenAI 兼容服务，支持连通性测试与模型 ID 配置
  • Agent 管理：系统提示词、温度、绑定模型；可选绑定工作流（控制台下拉选择）；可选绑定 MCP 工具（最多 10 个）；可选绑定知识库（最多 5 个，用于对话 RAG）
  • 对话：SSE 流式输出、多轮会话、Markdown 渲染；未绑工作流时支持 MCP 工具调用（最多 8 轮）与知识库 RAG 检索注入；绑工作流时同步执行引擎；会话列表显示 Agent 名称
  • 知识库 RAG：知识库 CRUD、文档上传（txt/md/pdf）、异步分块、向量化写入 pgvector、分块查询与删除；独立检索 API；Agent 绑定后对话自动检索并注入系统提示词
  • 工作流：可视化拖拽编辑器（START / LLM / CONDITION / END），查看/编辑/删除；Agent 绑定后通过对话触发 WorkflowEngine 执行
  • MCP 工具：MCP Server 注册、连通性测试、工具同步、调试调用；Agent 对话中自动加载已绑定工具
  • 管理控制台：深浅交替 UI（深色导航侧栏 + 浅色内容区）

开发进度

模块 状态 说明
hify-common ✅ BaseEntity、Result/PageResult、BizException、MyBatis-Plus 配置
hify-provider ✅ CRUD、连通性测试、健康状态、模型配置、Embedding API、usageType（llm/embedding）、工具调用 Schema
hify-agent ✅ CRUD、temperature、模型绑定、工作流绑定、MCP 工具绑定、知识库绑定
hify-chat ✅ SSE 流式、LLM 适配器、MCP 工具调用循环、对话 RAG 检索注入、会话/消息存储、工作流对话路由
hify-knowledge ✅ 知识库/文档 CRUD、分块管线、向量检索 API、MySQL + PostgreSQL 双数据源
hify-workflow ✅ 工作流 CRUD、WorkflowEngine 执行、节点运行记录
hify-mcp ✅ MCP Server 管理、客户端连接、工具发现与调用、调试接口
hify-web ✅ 模型/Agent/对话/知识库/工作流/MCP 管理页、Agent 工作流/知识库绑定、Embedding 提供商配置、可视化工作流编辑器

快速启动

环境要求：JDK 17+、Maven 3.8+、Node.js 18+、MySQL 8.x、Redis 7.x、PostgreSQL 18+（含 pgvector 扩展）

Redis 用于 Provider/Agent 配置缓存与会话上下文缓存，本地开发需先启动 Redis。

1. 准备 MySQL

mysql -uroot -p -e "CREATE DATABASE IF NOT EXISTS hify DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -uroot -p hify < hify-boot/src/main/resources/schema.sql

2. 准备 PostgreSQL（知识库向量）

# 创建数据库
psql -U postgres -c "CREATE DATABASE hify_knowledge;"

# 启用 pgvector 并建表
psql -U postgres -d hify_knowledge -c "CREATE EXTENSION IF NOT EXISTS vector;"
psql -U postgres -d hify_knowledge -f hify-boot/src/main/resources/schema-pg.sql

Windows 若未安装 pgvector，可从 pgvector_pgsql_windows 下载与 PostgreSQL 版本匹配的扩展包，解压到 PostgreSQL 的 share/extension、lib 目录后执行 CREATE EXTENSION vector;。

连接配置见 hify-boot/src/main/resources/application.yml 中的 hify.pg.*（可按本机修改）。

3. 启动后端

mvn clean install -pl hify-boot -am -DskipTests
mvn -pl hify-boot spring-boot:run

服务默认监听 **http://localhost:8080**。启动日志中应出现 HifyMySQLPool 与 HifyPgPool 两个连接池；首次启动会自动执行 MySQL / PostgreSQL schema 补丁（如 usage_type 列、向量维度迁移）。

4. 启动前端

cd hify-web
npm install
npm run dev

5. 验证

# 提供商列表
curl "http://localhost:8080/api/v1/providers?page=1&pageSize=5"

# 知识库列表
curl "http://localhost:8080/api/v1/knowledge-bases?page=1&pageSize=5"

# MCP Server 列表
curl "http://localhost:8080/api/v1/mcp-servers?page=1&pageSize=5"

浏览器访问 http://localhost:5173：在「模型管理」配置对话 LLM 与 Embedding 提供商 →「知识库」上传文档并等待向量化完成 →「Agent 管理」创建 Agent（可绑 MCP 工具、知识库或工作流）→「对话」开始聊天；也可在「工作流」用可视化编辑器创建流程后再绑到 Agent。

工作流说明

Agent 模型 vs LLM 节点模型

配置位置 何时生效 作用
Agent → 绑定模型 Agent 未绑工作流 普通对话、MCP 工具调用时使用
工作流 LLM 节点 → 绑定模型 Agent 已绑工作流 工作流内每一步 LLM 调用各自指定模型

绑工作流后，对话走 WorkflowEngine，不再使用 Agent 上的模型与 MCP；每个 LLM 节点必须配置 modelConfigId（用于问答、分类、生成回复等任意 Prompt，不限于意图检测）。

节点类型

类型 说明
START 入口，接收用户输入（nodeKey 必须为 start）
LLM 按节点 Prompt 调用大模型（需配置绑定模型、输出变量名）
CONDITION 条件分支（表达式支持 == / !=）
KNOWLEDGE 知识库检索（RAG，引擎支持）
API_CALL 调用外部 HTTP 接口（引擎支持）
END 结束并输出结果

可视化编辑器

  • 路由：/workflows/create（新建）、/workflows/:id（查看）、/workflows/:id/edit（编辑）
  • 左侧节点面板拖拽到画布，右侧配置节点属性（LLM 节点：模型、Prompt、输出变量名），支持连线/改边/删除边
  • CONDITION 节点的出边需标注 condition: "true" / "false"

触发方式

  1. 在「工作流」页面创建并保存工作流（可视化编辑器或 API）
  2. 在「Agent 管理」编辑 Agent，在「绑定工作流」下拉框中选择工作流（清空表示不绑定）
  3. 在「对话」页选择该 Agent 发送消息 → WorkflowEngine 同步执行 → SSE 返回 done 事件（无逐字流式 delta）

示例 JSON 见 docs/test-workflow.json、docs/wf-simple-qa.json、docs/wf-sentiment-routing.json、docs/wf-cs-routing.json。

执行记录可通过 GET /api/v1/workflows/{id}/runs/latest 查询。

MCP 说明

功能

  • 注册 MCP Server（名称、URL、传输方式自动检测：URL 以 /sse 结尾时使用 SSE 传输）
  • 测试连通性、同步工具列表、在线调试工具调用
  • Agent 绑定工具后，未绑工作流的对话中 LLM 可自动发起 tool call（最多 8 轮循环）

Agent 绑定工具

  1. 在「MCP 管理」添加 Server 并测试连通性
  2. 在「Agent 管理」编辑 Agent，通过工具选择器绑定（最多 10 个）
  3. 对话时系统自动加载有效工具，过滤已删除或禁用的绑定

传输方式

系统支持 2 种 MCP 传输（不支持 stdio）：

传输 触发条件
SSE Server URL 以 /sse 结尾
Streamable HTTP 其他 URL（默认）

连通性测试与工具同步时会自动选择对应传输，无需手动指定。

模型提供商配置说明

认证字段

authConfig 统一使用 apiKey 字段（兼容历史 api_key）。编辑提供商时 API Key 留空则保留原密钥。

DeepSeek（对话）

项 值
类型 OpenAI Compatible
API 地址 https://api.deepseek.com（不要带 /anthropic）
API Key DeepSeek 控制台密钥
模型 ID 如 deepseek-chat

DeepSeek 的 Anthropic 兼容入口（/anthropic）用于 Claude 协议对话；日常对话推荐使用 OpenAI Compatible 类型。

用途类型（usageType）

创建/编辑提供商时需选择用途：

usageType 说明
llm 对话、工作流 LLM 节点（默认）
embedding 知识库文档向量化、检索 query 向量化

Embedding 提供商仅参与 /v1/embeddings 调用，不会出现在对话模型下拉框中。

Embedding（知识库向量化）

知识库文档处理会调用 /v1/embeddings，需单独配置 usageType = embedding 的提供商：

提供商 类型 说明
OpenAI openai / openai_compatible 如 text-embedding-3-small（1536 维）
阿里云百炼等 openai_compatible 如 text-embedding-v4（1024 维）
DeepSeek — 不支持 /v1/embeddings，不能用于知识库向量化

默认 Embedding 模型为 text-embedding-v4（1024 维），可在 application.yml 的 hify.knowledge.default-embed-model / embedding-dimension 中修改。创建知识库时从 GET /api/v1/knowledge-bases/options/embedding-models 获取可选模型列表。

维度须一致：PostgreSQL t_knowledge_chunk.embedding 列维度须与 Embedding 模型输出一致。启动时 PgSchemaPatcher 会尝试自动迁移旧表（如 1536 → 1024）；也可手动执行 docs/knowledge-embedding-migrate.sql。

创建提供商检查清单

  1. 填写 API 地址与 API Key，并填写模型 ID
  2. 选择正确的 用途类型（对话 LLM 或 Embedding）
  3. 开启「启用」
  4. 点击「测试连接」确认成功
  5. 知识库场景：至少配置一个 Embedding 专用 提供商，并在知识库创建时选择对应模型

知识库说明

文档处理流程

上传文档 → PENDING → 解析文本 → 分块 → 调用 Embedding API → 写入 PostgreSQL → DONE
  • 元数据（知识库、文档记录）存 MySQL
  • 分块原文与向量存 PostgreSQL t_knowledge_chunk（默认 vector(1024)，对应 text-embedding-v4）
  • 支持格式：.txt、.md、.pdf（单文件最大 10MB）；txt 自动检测 UTF-8/UTF-16/GBK 编码
  • 上传目录默认 ./upload（可通过 hify.knowledge.upload-dir 配置）

对话 RAG

Agent 未绑工作流时，每次用户提问会：

  1. 读取 Agent 绑定的知识库 ID 列表（最多 5 个）
  2. 对各知识库执行向量检索（默认 topK=5，余弦相似度 ≥ 0.45）
  3. 将命中分块注入系统提示词后调用 LLM

配置项（application.yml → hify.knowledge.rag）：

项 默认 说明
top-k 5 每轮最多注入的分块数
min-similarity 0.45 相似度阈值，低于此值的分块丢弃

绑定步骤：「知识库」上传并完成向量化 →「Agent 管理」编辑 Agent → 选择「绑定知识库」→ 对话页选择该 Agent 提问。

独立检索 API（不经过 LLM）：

curl "http://localhost:8080/api/v1/knowledge-bases/{id}/search?q=金卡会员&topK=5"

Agent 知识库绑定 API：

# 查询绑定
curl "http://localhost:8080/api/v1/agents/{id}/knowledge-bases"

# 更新绑定（最多 5 个）
curl -X PUT "http://localhost:8080/api/v1/agents/{id}/knowledge-bases" \
  -H "Content-Type: application/json" \
  -d '{"knowledgeBaseIds": [1, 2]}'

双数据源架构

数据源 Bean 用途
MySQL @Primary dataSource MyBatis-Plus 业务表
PostgreSQL pgDataSource / pgJdbcTemplate 向量分块读写

配置类：hify-boot/src/main/java/com/hify/config/DataSourceConfiguration.java

模块结构

模块 说明
hify-common 公共模块
hify-provider 模型提供商与模型配置
hify-agent Agent 配置、MCP 工具绑定、知识库绑定
hify-chat 对话引擎（LLM + MCP + RAG + 工作流路由）
hify-knowledge 知识库 RAG
hify-workflow 工作流 CRUD 与执行引擎
hify-mcp MCP Server 管理与客户端
hify-boot 启动入口、双数据源装配、Redis 缓存配置
hify-web 管理控制台前端

API 文档

统一响应格式 Result<T> / 分页 PageResult<T>、错误码约定见 docs/api-common.md。

模块 文档 Base URL
模型提供商 docs/provider-api.md /api/v1/providers
Agent docs/agent-api.md /api/v1/agents
对话 docs/chat-api.md /api/v1/conversations
知识库 docs/knowledge-api.md /api/v1/knowledge-bases
工作流 docs/workflow-api.md /api/v1/workflows
MCP docs/mcp-api.md /api/v1/mcp-servers

健康检查：GET /health → success

常见问题

现象 处理
上传 txt 报「内容为空」 确认文件非空；后端已支持 UTF-8 BOM / UTF-16 / GBK 自动检测
对话不引用知识库内容 确认 Agent 已绑定知识库且文档状态为 DONE；Agent 不能绑工作流（工作流走独立引擎）
Agent 对话不调用 MCP 工具 确认 Agent 已绑定工具且 Server 启用；查看后端日志是否加载工具列表
工作流对话无流式输出 工作流为同步执行，仅推送 done/error，无 delta；属预期行为
Agent 绑了工作流却不走 MCP / RAG 绑工作流时走 WorkflowEngine，不走 Agent 模型、MCP 与对话 RAG 路径

About

基于Dify的AI Agent开发平台

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages