项目简介

AgentForge 是一个自托管的 AI Agent 数据平台。支持上传文档或连接 27 种外部数据源（对象存储、关系型数据库、OLAP、NoSQL、文档平台、代码仓库、企业云），通过 混合检索（向量余弦相似度 + BM25 重打分 + 可选 Cross-Encoder 精排）返回高质量上下文，并通过 MCP / Skill 将数据无缝集成到 Claude Desktop / OpenClaw / Hermes 等智能体应用。

项目采用 Python 3.11+ 开发，后端使用 FastAPI 框架，前端采用 Bulma CSS + Alpine.js。向量数据库默认使用 ChromaDB，可切换为 PostgreSQL + pgvector。嵌入模型使用本地 sentence-transformers（all-MiniLM-L6-v2），无需外部 API 密钥。APScheduler 负责外部数据源的定时增量同步。

安装指南

环境要求

• Python 3.11 或更高版本
• 可选：PostgreSQL 数据库（默认使用 SQLite）
• 可选：pgvector 扩展（用于 PostgreSQL 向量存储）

通过 PyPI 安装（推荐）

pip install agentf

源码安装

git clone https://github.com/canmengfly/AgentForge.git
cd AgentForge
python -m venv .venv && source .venv/bin/activate
pip install -e .

启动服务

agentf-api

启动后访问 http://localhost:8000，默认账户为 admin / admin123。

快速开始

1. 登录系统

启动后访问 http://localhost:8000，使用默认账户 admin / admin123 登录，首次登录后请立即修改管理员密码。

2. 创建集合

在管理界面创建文档集合，用于组织不同主题的知识文档。每个用户的数据位于专属命名空间 u{user_id}_{collection_name}，服务端严格隔离。

3. 添加数据

两种方式任选一种或组合：

• 上传文档：支持 TXT / MD / HTML / PDF / DOCX 文件上传或粘贴文本
• 连接外部数据源：在「数据源」页面选择 27 种连接器之一，配置凭证 + 同步间隔，调度器将自动同步内容到向量库

4. 测试检索

使用混合检索功能验证效果。调用 POST /me/search/all 可在所有集合（上传文档 + 外部数据源）统一检索，结果经向量相似度 + BM25 重打分后返回 Top-K。

5. 配置 MCP / Skill

在「Agent 集成」页面一键生成 MCP 配置 JSON 或下载 Skill YAML，将 AgentForge 无缝接入 Claude Desktop / OpenClaw / Hermes 等智能体应用。

功能特性

用户数据隔离

每个用户的文档存储于专属 ChromaDB 集合：u{user_id}_{collection_name}。命名空间前缀在服务端强制校验——用户 A 无法访问用户 B 的数据。

外部数据源

AgentForge 支持 27 种外部数据源，可定时同步并与上传文档一同检索。

支持的连接器

添加数据源

1. 侧边栏进入「数据源」页面
2. 点击「新建数据源」，选择类型并填写连接凭证
3. 点击「测试连接」验证凭证有效性
4. 设置同步间隔（如 30 分钟）并保存
5. 调度器自动同步内容到你指定的集合

同步行为

• 全量同步：首次运行拉取全部内容
• 增量同步：后续运行仅拉取新增 / 修改内容（数据源支持者）
• 同步的文档出现在你指定的集合中，即时可检索

文档管理

AgentForge 提供完整的文档生命周期管理功能，包括上传、查询和删除操作。

支持的文件格式

混合检索

AgentForge 的检索结果由两路信号融合而成：

1. 向量相似度——sentence-transformers 余弦距离，应用于所有集合
2. BM25 重打分——词频排序，针对结构化 SQL 数据源（MySQL / PostgreSQL / Oracle / SQL Server / TiDB / OceanBase / Doris / ClickHouse / Hive / Snowflake）

可选启用 Cross-Encoder 精排器，使用专用相关性模型进一步精排结果顺序。

检索流程

1. 用户输入查询文本
2. 向量检索并行汇总（fan-out）各集合候选结果，初始候选池为 top_k × 4
3. SQL 类数据源叠加 BM25 重打分（k₁=1.5，b=0.75）
4. 可选 Cross-Encoder 精排
5. 按 doc_id 去重并返回 Top-K

评分融合

向量相似度与 BM25 分数归一化到 [0, 1] 后按以下公式混合：

final_score = α · vector_score + (1 - α) · bm25_score

混合权重 α 对 SQL 类集合默认为 0.5，对纯向量源为 1.0。

推荐精排模型

统一检索 API

POST /me/search/all
Content-Type: application/json

{
  "query": "quarterly revenue by region",
  "top_k": 10
}

该接口跨你的所有集合（上传文档 + 同步的外部数据源）运行混合检索，返回统一排序的结果列表。

嵌入模型

默认 sentence-transformers/all-MiniLM-L6-v2，本地运行，维度 384，无需外部 API 密钥；可通过 EMBEDDING_MODEL 环境变量切换为其他 sentence-transformers 模型。 启用精排时可配置 RERANKER_MODEL（例如 cross-encoder/ms-marco-MiniLM-L-6-v2）。

用户认证

AgentForge 采用 JWT 认证机制，令牌存储在 httpOnly Cookie 中，有效防止 XSS 攻击。

安全特性

• 密码使用 bcrypt 加密，cost factor 为 12
• JWT 令牌设置合理过期时间
• 支持禁用用户账户
• 用户数据在存储层级隔离

MCP 服务器集成

MCP（Model Context Protocol）是 Anthropic 推出的开放协议，用于标准化 AI 助手与外部数据源和工具的连接方式。AgentForge 提供 MCP 服务器实现，让 Claude 可以直接访问你的知识库。

提供的工具

配置方法

在「Agent 集成」页面，系统会自动生成 MCP 配置 JSON，拷贝至 Claude Desktop 配置文件即可。同时支持下载 Skill YAML，以即用形式接入 OpenClaw / Hermes 等支持 Skill 协议的智能体应用。页面还提供 API 测试控制台，可在浏览器内验证各工具。

传输方式

当前采用 stdio（标准输入输出）传输，由 Claude Desktop / Claude Code 按需拉起——无需手动启动 MCP 服务。

API 文档

AgentForge 提供完整 RESTful API，所有端点都接收和返回 JSON。支持两种认证方式：浏览器自动携带的 JWT httpOnly Cookie，或请求头中的 Authorization: Bearer aft_xxx。

用户文档端点 /me/*

数据源端点 /me/datasources

API Token 端点 /me/tokens

管理员端点 /api/admin/*

检索请求示例

POST /me/search
Content-Type: application/json
Authorization: Bearer aft_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "query": "什么是向量数据库？",
  "collection": "notes",
  "top_k": 5
}

检索响应示例

{
  "results": [
    {
      "chunk_id": "xyz789",
      "doc_id": "abc123",
      "content": "向量数据库是一种专门设计...",
      "score": 0.892,
      "metadata": {
        "source_type": "mysql",
        "table": "products"
      }
    }
  ]
}

环境配置

所有配置均通过环境变量读取，支持 .env 文件。

.env 示例

DATA_DIR=/var/agentforge/data
JWT_SECRET=replace-with-a-random-32-char-string
VECTOR_BACKEND=chroma
EMBEDDING_MODEL=all-MiniLM-L6-v2
RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2