# ai-flow

**Repository Path**: zhao_pengfei_code/ai-flow

## Basic Information

- **Project Name**: ai-flow
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-27
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Flow

基于 TypeScript、Zod 和 React Flow 的轻量 LLM 工作流。支持可视化节点编排、多模型配置、独立知识库、测试运行和发布 API。

## 系统展示
![img_0](docs/screenshots/img_0.jpg)
![img_1](docs/screenshots/img_1.jpg)

## 启动

需要 Node.js 22.12+ 和 PostgreSQL 16 + pgvector。

```bash
npm install
# 新项目可复制 .env.example 为 .env；已有 .env 请添加新增变量，不要覆盖原文件
# 设置 .env 中的 PostgreSQL、管理密钥和模型配置
docker compose up -d postgres
npm run dev
```

打开 `http://127.0.0.1:8787`，使用 `ADMIN_API_KEY` 登录管理工作台。生产部署直接执行 `docker compose up -d --build`。

## 模型配置

顶部“模型”页面可以创建多个兼容 OpenAI API 的连接，每个连接可配置多个对话模型或 Embedding 模型。创建后先用“测试”检查接口与模型名称，再在大模型或决策路由节点中明确选择对话模型；未选择模型的节点不能运行或发布。API Key 只传给服务端，服务端使用 AES-GCM 加密保存到 PostgreSQL；`APP_ENCRYPTION_KEY` 必须固定并妥善保管。

使用 Docker Compose 运行应用、Ollama 运行在宿主机时，连接地址填写 `http://host.docker.internal:11434/v1`。Compose 会为应用容器添加该主机名；如果 Docker 的默认宿主机网关无法访问 Ollama，请在 `.env` 设置 `HOST_DOCKER_INTERNAL_IP` 为容器可访问的宿主机 IP（Windows/WSL 环境通常是 WSL 虚拟网卡的 IPv4 地址），然后执行 `docker compose up -d --force-recreate app`。该地址仅用于容器内解析，不需要修改页面里已保存的连接。

现有 `.env` 中的 `OPENAI_API_KEY`、`OPENAI_BASE_URL`、`OPENAI_MODEL` 会显示为只读的环境变量对话模型。设置 `OPENAI_EMBEDDING_MODEL` 后，同一连接还会显示环境变量 Embedding 模型。若聊天服务不支持 Embedding，请在页面里另建连接。修改 `.env` 后需重启服务。

## 知识库

顶部“知识库”页面创建知识库时选择 Embedding 模型；一个知识库固定使用一个模型。上传 TXT、Markdown 或 PDF（单文件最多 10 MB）后，LangChain.js 会按段落切分文本，并调用所选模型生成 Embedding，pgvector 保存向量和来源。页面会显示排队、索引百分比和完成状态，并提供试检索。扫描版 PDF 需要先 OCR。

在工作流的知识检索节点选择知识库，并配置查询、Top K 和最低相关度。检索结果可通过 `{{input}}` 传给下游节点；跨节点取值使用 `{{context.节点ID.output}}`。逐节点运行结果还会给出命中文档来源。

知识库页面可预览已索引文档的文本块与 PDF 页码；试检索结果可跳转到对应文本块。预览直接读取 PostgreSQL 中已保存的内容，不会再次生成向量。

## 工作流

1. 从画布添加节点，拖动右侧出口连接下一个节点。条件节点有“是”和“否”两个出口。
2. 点击节点配置输入、模型、HTTP 请求或知识库。`input` 表示当前节点唯一直接上游的原始 `output`，可用 `{{input}}` 或 `{{input.field}}` 读取；`context` 表示已执行节点上下文，统一为 `context[节点ID] = { input, output }`，模板使用 `{{context.节点ID.output}}` 或 `{{context.节点ID.input}}`。
3. 决策路由节点会把输入交给对话模型，从配置的选项中选择一个 key，并沿对应出口继续执行；模型无法返回合法 key 时走“默认”出口。所有对话和决策模型统一使用 OpenAI 兼容协议，连接地址填写服务商提供的 `/v1` 地址，例如 Ollama 使用 `http://127.0.0.1:11434/v1`，API Key 填服务商要求的值，模型名称填写对应模型 ID（例如 `tev1:0.8b`）。
4. “测试运行”查看结果与逐节点执行信息；保存后可以发布为 API。发布时会检查模型引用和知识库索引状态。

大模型节点使用 OpenAI 兼容接口的 SSE 流式响应；测试运行通过运行会话 SSE 事件流持续展示当前节点已生成的内容，并在连接短暂中断时自动重连。模型接口不支持流式响应时会自动兼容一次性 JSON 响应。

代码处理节点可以运行同步 JavaScript：脚本直接使用 `input` 获取直接上游结果，使用 `context` 获取已执行节点上下文。开始变量来自表单，值为字符串；例如两数相加使用 `return Number(input.a) + Number(input.b);`。脚本在受限 VM 中执行，不能访问文件、网络、环境变量、`process` 或 `require`；执行时间受节点超时配置限制。

编辑器工具栏提供撤销和重做；选中节点后可复制节点，选中连线后可删除连线。也可以使用 `Ctrl/Cmd+Z` 撤销、`Ctrl/Cmd+Shift+Z` 或 `Ctrl/Cmd+Y` 重做、`Ctrl/Cmd+D` 复制节点。发布前会校验节点连通性、分支出口、循环和外部模型/知识库资源，并在工具栏列出具体错误。

编辑器工具栏可将当前工作流导出为 `.ai-flow.json`，也可导入该文件。导出前会保存当前修改；导入与已有 ID 冲突时会创建副本。文件包含工作流图和节点配置，不包含模型密钥、知识库文档或发布记录。导入后如引用了原环境的模型或知识库，需要重新选择可用资源。

“运行记录”保存最近 100 次测试与已发布 API 调用，可按工作流、来源和状态筛选。运行异常和取消也会生成记录；记录保存在 PostgreSQL，包含状态、耗时与逐节点错误，不保存输入或输出正文。

测试运行会实时显示当前节点、已完成节点数和耗时；异步运行会话支持 SSE 事件流、状态查询和取消，取消或失败时会保留已完成的节点明细。

发布后调用：

```bash
curl -X POST http://127.0.0.1:8787/api/workflows/demo-qa/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"inputs":{"message":"你好"}}'
```

需要异步执行时，在调用 URL 追加 `?async=true`。接口会立即返回 `202`、运行会话 ID、`statusUrl` 和 `eventsUrl`；客户端可以订阅 `eventsUrl` 接收 `snapshot`、`update` 和 `complete` 事件，也可以通过 `statusUrl` 查询状态；状态为 `running` 时可调用 `POST /api/run-sessions/:id/cancel` 取消运行。

每次发布创建一个独立版本。API 页面可查看版本、恢复旧版本或取消发布；恢复不会覆盖当前草稿。首次发布会生成工作流专属密钥，只显示一次；可在 API 页面轮换，旧密钥会立即失效。升级前已发布的工作流需要先在 API 页面生成密钥，才能继续调用。当前管理接口仍只适合本机使用，公网部署还需要管理端鉴权。

工作流、模型、知识库元数据、文档原件、文本块和 pgvector 向量均保存在 PostgreSQL。工作流图和发布快照使用 `jsonb`，工作流、模型连接、模型、知识库和文档元数据分别使用独立表；`app_state` 仅用于系统级状态，不再承载这些领域数据。`npm run build` 构建前端，`npm start` 提供构建后的页面和 API。

## 当前范围

- 模型连接仅支持 OpenAI 兼容的 Chat Completions 和 Embeddings 接口。
- 文档索引任务一次执行一个；排队、索引进度、更新时间和重试次数保存在 PostgreSQL。服务重启后会自动恢复未完成任务，并根据已落库的连续文本块继续处理；每批向量写入事务，完成前会校验文本块数量，避免残留旧块被检索。索引任务开始前会用数据库原子领取文档，避免多实例重复处理。Embedding 模型或 PostgreSQL/pgvector 不可用时任务会显示失败，可在页面重试。
- 管理端使用 `X-Admin-Key` 鉴权；已发布工作流的运行 API 使用 Bearer Key。全局和发布运行接口均有 PostgreSQL 计数限流，API 请求写入审计日志。部署公网前仍需配置反向代理 TLS 和 HTTP 请求目标限制。
- 发布版本冻结工作流图，但引用的模型连接与知识库内容是当前版本；修改或删除外部资源可能影响已发布调用。

管理密钥只放在浏览器会话存储中。管理 API 通过 `X-Admin-Key` 调用；审计记录可通过 `GET /api/audit` 查看，包含请求时间、路径、状态和耗时，不保存请求体。`API_RATE_LIMIT` 与 `RUN_RATE_LIMIT` 分别控制每个来源地址每分钟的 API 总请求数和发布运行次数。公网部署请使用 HTTPS 反向代理，且只信任代理提供的来源地址。

生产日志使用单行 JSON 输出到 stdout/stderr，包含时间、级别、请求 ID、路径、状态和耗时；`LOG_LEVEL` 可设置为 `info`、`warn`、`error` 或 `silent`。日志会自动隐藏密钥、Authorization、请求输入和模型输出。Docker Compose 已配置容器日志轮转（每个文件 10 MB，保留 3 个）。

LLM 和决策节点的模型请求默认超时 5 分钟，可通过 `LLM_TIMEOUT_MS` 调整，允许范围为 1 秒到 10 分钟。节点面板也可以为单个节点填写超时，留空时继承全局设置。超时包含模型连接和完整流式输出时间；运行取消仍由运行会话的取消信号单独控制。

监控接口包括：`GET /api/health/live`（进程存活，不访问数据库）、`GET /api/health/ready`（检查 PostgreSQL，失败返回 503）、`GET /api/health`（公开摘要）和需要 `X-Admin-Key` 的 `GET /api/metrics`（JSON）以及 `GET /api/metrics/prometheus`（Prometheus 文本格式）。指标包含请求错误率和耗时、工作流成功/失败/取消与活跃数、知识库索引队列和失败数、进程内存与 CPU 使用量。

## 检查

```bash
npm test
npm run build
```

开发者入口：[docs/README.md](docs/README.md)。