Skip to content

ARKL5/FUXI

BranchesTags

Repository files navigation

FUXI / OneKE 六智能体知识抽取平台

OneKE 是一套围绕 “六智能体 + 统一 Pipeline” 打造的知识抽取平台，涵盖前端可视化、FastAPI 后端、Supabase 数据服务与 Python 核心引擎。你可以通过 Web 端拖拽文件、实时监控任务、导出知识图谱，也可以直接调用 CLI/SDK 将抽取能力集成到自己的系统中。

✨ 功能亮点

  • 多任务知识抽取：支持 NER / RE / EE / 三元组任务，核心 Pipeline 由 Schema / Extraction / Graph 等智能体协同完成。
  • 全链路体验：React 19 + Vite 前端提供上传、任务调度、结果分析、图谱可视化与模型配置；FastAPI 后端负责鉴权、任务编排、导出、WebSocket 推送。
  • 模型即插即用：默认 DeepSeek，可通过 API/配置切换到 OpenAI、Qwen、Anthropic、Gemini、智谱或自建模型，并对密钥做加密存储。
  • 工程化建设：使用 uv 管理依赖、Supabase 管理数据 schema，配套死文件扫描、WS/缓存封装、任务状态机与监控日志。
  • Prompt / LLM 统一服务：LLMService + PromptBuilder 统一管理指令模板、语言提示、JSON 解析与临时超参，CLI、Runtime、后端共用一套调用链，便于接入自定义模型；默认 few-shot 按语言/任务储存在 src/prompts/default_few_shots.yaml，可按需拓展。
  • 反思智能体加速链：抽取阶段后自动接入 ReflectionAgent，启发式 ⇄ LLM 并行执行，可在不显著增加延迟的情况下校验/补写结果并触发局部重试。
  • 自动降级：缓存、质量增强、图谱优化等模块在依赖缺失时会自动回退，确保最小可用。

🧱 顶层架构

FUXI/
├── frontend/        # Vite + React 19 SPA
├── backend/         # FastAPI 服务，调用 Supabase & 核心引擎
├── src/             # 六智能体核心 Pipeline / Hooks / 工具
├── examples/        # 配置样例与脚本
├── scripts/         # 调试/仿真脚本（如 simulate_upload_flow.py）
├── data/, exports/, uploads/  # 运行期数据（`data/cases/<locale>.json` 为案例库）
└── shared/, tests/, config/   # 公共模块 & 测试资产

各子目录均有独立 README（例如 frontend/README.md, backend/README.md, src/README.md）详细说明模块内部结构与命令。

🚀 快速开始

0. 环境准备

  • Python ≥ 3.10（推荐 3.11）并安装 uv。
  • Node.js ≥ 18（pnpm/npm 任选）。
  • Supabase 项目：准备 SUPABASE_URL 与 SUPABASE_SERVICE_ROLE_KEY（用于服务端密钥）。
  • 可选：Redis Stack（如果需要更强的缓存/时序能力，核心模块已能自动降级）。

1. 克隆仓库

git clone <repo-url>
cd FUXI

2. 安装依赖（uv 推荐）

uv venv
source .venv/bin/activate   # Windows 使用 .venv\Scripts\activate

uv pip install -r requirements.txt
uv pip install -r backend/requirements_backend.txt

cd frontend && npm install && cd ..

RapidFuzz 说明：src/knowledge_extraction/postprocess/triple_validator.py 现仅依赖 RapidFuzz 提供的 Jaro-Winkler 与 Levenshtein 相似度，所有 difflib/自定义实现已删除。请分别运行 uv pip install -r requirements.runtime.txt 与 uv pip install -r backend/requirements_backend.txt，确保核心 Pipeline 与后端环境都安装 rapidfuzz==3.10.1，否则三元组去重会因缺少依赖而报错。

3. 配置环境变量

在仓库根目录创建 .env（或 .env.local），示例：

SUPABASE_URL="https://xxx.supabase.co"
SUPABASE_SERVICE_ROLE_KEY="sbp-srv-key"

DEEPSEEK_API_KEY="sk-xxx"
DEEPSEEK_MODEL="deepseek-chat"
DEEPSEEK_BASE_URL="https://api.deepseek.com"

ENCRYPTION_SECRET="32-bytes-secret"   # 与 shared/security/encryption 保持一致
ONEKE_DISABLE_FILE_LOG=0              # 1=仅输出到控制台

更多后端变量请参考 backend/README.md 的环境表。

Embedding 模型缓存策略

  • 默认使用 sentence-transformers/all-MiniLM-L6-v2，首次运行会把权重下载到 TRANSFORMERS_CACHE（默认 ~/.cache/transformers）以及 EMBEDDING_CACHE_DIR（默认 ~/.cache/torch/sentence_transformers）。
  • 之后 CLI / 后端服务会优先复用本地缓存或 EMBEDDING_MODEL_LOCAL_PATH 指定路径，避免重复下载；将 EMBEDDING_SAFE_MODE=1 可强制离线模式。
  • 可用的相关环境变量：
    • HF_ENDPOINT / HF_FALLBACK_ENDPOINT：主/备下载源
    • EMBEDDING_MODEL_DOCKER_PATH：容器内预置模型目录
    • TRANSFORMERS_CACHE、EMBEDDING_CACHE_DIR：缓存根目录

缓存命中时日志会打印 ✅ [EmbeddingManager] 使用本地模型: ...snapshots/...，表明已直接从磁盘加载。

反思智能体配置

  • src/config/unified_config.yaml 中 agent.enable_reflection 控制是否插入 ReflectionAgent 阶段。
  • agent.reflection 支持：
    • max_review_workers：并发 LLM 校验数量；
    • stage_timeout：反思阶段允许等待异步 LLM 的时间（秒，0 表示完全并行，结果在总结阶段再收敛）；
    • finalize_timeout：进入总结阶段前的最大等待时间；
    • retry_threshold / duplicate_threshold：启发式触发条件；
    • enable_llm_review：是否启用 LLM 深度校验。
      这些参数可通过 --pipeline-config 或环境变量覆盖，便于在离线/在线环境间切换不同的反思策略。

4. 启动服务

# 后端
cd backend
uvicorn main:app --reload --port 8000

# 新终端 -> 前端
cd frontend
npm run dev

5. CLI / SDK 验证（可选）

python src/main.py --task Triple --text "苹果公司于1976年成立"

CLI 会优先读取 DEEPSEEK_API_KEY/DEEPSEEK_MODEL/DEEPSEEK_BASE_URL 等环境变量；若缺失则回落到 examples/config/quick_start_config.yaml。Pipeline 配置可通过 --pipeline-config 覆写，若未指定则读取 ONEKE_PIPELINE_CONFIG 环境变量，再回落到 src/config/unified_config.yaml，这些解析逻辑统一由 ConfigLoader 处理。案例库会在运行期写入 data/cases/<locale>.json，确保仓库具有写权限。

查看反思轨迹

uv run python src/knowledge_extraction_cli.py \
  --task Triple \
  --mode standard \
  --show-trajectory \
  --text "长文本 ..."

--show-trajectory 会在输出体中展示 trajectory.reflection，包含 ReflectionAgent 启发式检测、异步 LLM 审核备注（notes）与 retry 记录，便于快速诊断模型幻觉或并发修复是否触发。

📁 目录导航

目录 描述 文档
frontend/ React 19 + Vite UI，提供上传、任务监控、图谱分析、模型设置 frontend/README.md
backend/ FastAPI 服务，整合 Supabase、任务调度、WebSocket、导出 backend/README.md
src/ 六智能体核心引擎与 Pipeline（KnowledgeExtractionApp、UnifiedPipeline 等） src/README.md
scripts/ 调试脚本（如 simulate_upload_flow.py - 演练文件上传流程） 脚本内注释
examples/ 配置与使用示例（如 config/quick_start_config.yaml） 目录内说明
tests/ 端到端与单元测试资产 pytest
data/cases/ 多语言案例库存储目录（按 en/zh/ja 划分） 本文 “多语言案例库”

🔧 开发与调试

常用命令

# 后端测试
pytest backend/tests

# 核心引擎/通用测试
pytest src/tests -m "not slow"

# 死文件扫描（前端）
cd frontend && npm run dead-files

有用脚本

  • scripts/simulate_upload_flow.py：使用 Fake Supabase Client 重放 “上传 → 入库 → 执行 → 写回” 全流程，适合在本地没有 Supabase 时调试。
  • scripts/redis_*：备份/恢复 Redis 的工具（如仍需 Redis Stack 场景）。
  • tests/test_extraction_services.py：覆盖 ConstraintService、ChunkExtractor、TripleMerger 的关键逻辑，是所有抽取任务的最小单测入口。

Prompt 模板与语言定制

  • 所有任务/语言的提示语集中在 src/prompts/instruction_templates.yaml，修改后可通过 knowledge_extraction.common.models.prompt_template.reload_instruction_templates() 热更新。
  • ExtractionAgent 会根据输入文本自动选择 EN/JA/ZH 模板；若需要锁定输出语言，可在 YAML 中维护不同语言的模板或在任务配置里设置 language_lock。
  • 指令模板与 Schema 相分离：SchemaAgent 继续使用 JSON Prompt + Pydantic schema 描述字段，如需统一字段语言，可在模板或结果后处理阶段覆盖。
  • SchemaAgent 相关 prompt 已完整序列化为合法 JSON，并在日志中以 schema:text_analysis / schema:deduce 标签输出，ONEKE_DUMP_PROMPT=1 时可直接捕获并排查。
  • 所有抽取模板默认附带“仅输出 JSON、禁止解释/markdown”约束；PromptConfig.json_only 可按需关闭，但生产环境建议保持开启以避免模型输出额外文本。
  • llm_profiles.yaml 中所有 temperature 现统一收敛到 ≤0.1，LLMService 也会在运行期通过 normalize_temperature 进行再约束，确保调用链稳定；若某些供应商要求最低温度，可通过环境变量 LLM_PROVIDER_MIN_TEMPERATURE 覆写。
  • 默认 few-shot 汇总在 src/prompts/default_few_shots.yaml，按语言 + 任务组织示例，CLI/Runtime 缺少案例时会自动加载，可直接追加或覆盖；LLM 超参配置集中在 src/config/llm_profiles.yaml，例如为 Triple 抽取单独设置 temperature/top_p/max_tokens，由 ChunkExtractor/LLMService 统一读取，避免硬编码。

案例翻译与自动写库

  • CLI 或 Pipeline 命中案例不足时会触发英语案例翻译兜底。若运行命令时指定 --update-case（或在 API 中传入 update_case=True），系统会将翻译后的示例写回对应语言的案例库（路径默认 data/cases/<locale>.json）。
  • 每次写库都会附带翻译结果与原始任务类型，后续同语言请求即可直接命中，不再依赖实时翻译（显著降低 fallback 耗时与成本）。
  • 若希望强制离线扩充案例，可配合 scripts/augment_cases.py 与 translation 配置中的 DeepSeek API Key，统一批量翻译后再运行 CLI 进行验收。
  • 若仓库升级自旧版本：首次运行 _LocaleRepoMixin 会自动将 src/knowledge_extraction/extract/knowledge_base/case_repository*.json 迁移到 data/cases/，无需手动操作。

日志

  • 默认写入 backend/logs/，可设置 ONEKE_DISABLE_FILE_LOG=1 仅输出到 stdout。
  • CLI 可以通过 --log-level（默认 warning）或 --quiet 控制终端噪声；同样也可在环境中设置 ONEKE_LOG_LEVEL=info|debug|silent 统一覆盖，CI 的 CLI Smoke workflow 会以 --log-level debug 跑一次冒烟，确保新增模块没有遗留裸 print。
  • WebSocket / 缓存命中率调试：ONEKE_VERBOSE_CACHE_LOG=1。

环境变量速查

作用域 变量 含义
Supabase SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, SUPABASE_ANON_KEY 连接/密钥
模型 DEEPSEEK_API_KEY, DEEPSEEK_MODEL, DEEPSEEK_BASE_URL（或其他 provider 自定义变量） 默认模型与用户兜底配置
加密 ENCRYPTION_SECRET 与 shared/security/encryption 对应，确保密钥长度满足要求
调度 TASK_RESULT_MAX_RETRIES, TASK_RESULT_RETRY_DELAY 等 后端任务执行/重试策略
优化 ONEKE_USE_OPTIMIZATION, ONEKE_VERBOSE_CACHE_LOG, ONEKE_DASHBOARD_CACHE_DISABLED Pipeline 优化与缓存开关
文本切分 KB_CHUNK_LIMIT, KB_CHUNK_DYNAMIC, KB_CHUNK_DENSE_LIMIT, KB_CHUNK_OVERLAP, KB_CHUNK_MIN, KB_CHUNK_MAX 影响 src/knowledge_extraction/preprocess/chunk_config.py 的切分参数；KB_CHUNK_DYNAMIC 支持 1/0、true/false、on/off 等大小写不敏感写法
分块策略 KB_CHUNK_STRATEGY, KB_CHUNK_TOKENIZER_MODEL, KB_CHUNK_SENTENCE_MODEL strategy 可选 recursive_tiktoken / token_strict / sentence_transformer；后两者分别指定 tiktoken 模型与 SentenceTransformers 模型，默认使用 sentence-transformers/all-MiniLM-L6-v2 保证语义完整

小提示：如果你在部署中写了 KB_CHUNK_DYNAMIC=true 却发现动态分片未生效，请确保变量值没有被额外的引号包裹成 "true"（YAML/JSON 中应写成无引号布尔或单独的字符串字段）。

✅ 测试

项目已附带端到端与模块化用例，推荐在开发/CI 中运行：

# 全量测试（默认 `tests/` 下所有用例）
pytest

# 分模块调试
pytest tests/runtime/test_chunk_group_executor.py
pytest tests/test_extraction_services.py -k triple

Runtime 相关逻辑已收敛至统一的 PipelineCommand 和后处理管线；若调整运行时行为，请优先运行 tests/test_pipeline_smoke.py 等管线冒烟用例确保无回归。

🧪 质量保障

  • Lint / 类型：前端使用 ESLint + TypeScript 严格模式；后端/核心推荐搭配 ruff 或 mypy（可按需添加到 uv 命令）。
  • 测试分层：
    • backend/tests/test_websocket_performance.py: WebSocket / 性能验证。
    • tests/test_pipeline_smoke.py: Pipeline 级冒烟。
    • tests/test_runner_*: 多分支任务覆盖。
    • tests/test_api_submit.py: 端到端接口校验。
    • tests/test_case_repository_unified.py: 多语言案例库检索/写入回归。
    • tests/test_locale_and_translation.py: locale 传递与翻译兜底逻辑。
  • 推荐命令：pytest tests/test_case_repository_unified.py tests/test_locale_and_translation.py
  • 前端死文件：npm run dead-files 生成 dead-files-report.json，CI/提交前可复查。
  • 模拟脚本：scripts/simulate_upload_flow.py 为 CI 环境提供无外部依赖的流程保障。

❓ 常见问题

问题 处理方式
Supabase 连接失败 检查 .env 是否包含 SUPABASE_URL 与服务端密钥；必要时重新生成密钥或启用 ONEKE_DB_DISABLE_PING=1 简化启动。
任务长时间停留在 pending 查看 backend/logs/background_task_processor.log；确认 DEEPSEEK_API_KEY 可被子进程读取，或在 CLI 中验证核心引擎是否可用。
WebSocket 无推送/频断 前端需在连接后发送 subscribe；也可调低前端 useTaskWebSocket 的 reconnectInterval。
新用户默认模型为空 确保后端环境存在 DEEPSEEK_*，并重启服务；登录/注册流程会通过 utils/model_defaults.py 自动写入。
导出文件过多 定期清理 backend/exports/ 与 backend/uploads/，或改为挂载对象存储。

📚 参考文档

  • 前端使用说明：frontend/README.md
  • 后端服务说明：backend/README.md
  • 核心引擎 / CLI：src/README.md
  • 示例与配置：examples/
  • 多语言案例库策略：docs/multilingual_cases.md
  • 管道探针：scripts/locale_pipeline_smoke.py（快速验证 zh/ja NER 流）

⚠️ 如未在 translation.api_key_env（或 translation.api_key）中提供可用密钥，翻译链路会自动回退到公共 HTTP 服务，吞吐与稳定性都有限，建议在批量扩充案例前先配置 DeepSeek 等自有翻译凭据。

聚合模块与扩展指引

  • src/knowledge_extraction/extract/aggregation/ 存放所有多 chunk 结果聚合器，当前默认导出的 AnswerSummarizer 会在 ExtractionAgent 中被注入；新增自定义聚合策略时，请在该目录添加模块并更新 __all__，方便其他调用方显式导入。
  • 若聚合器需要额外的去重逻辑，可以实现 TripleDeduper 并通过依赖注入传递，避免在核心 Agent 中反复粘贴同样的后处理代码。
  • 任何新增聚合模块应至少包含一组 pytest 覆盖“顺序保持 + 去重”两个维度；可参考 tests/test_answer_summarizer.py 的写法快速搭建回归用例。

欢迎在 GitHub Issue 中反馈问题或发起 Pull Request；提交前请运行相关测试并更新相应 README/文档。让我们一起让知识抽取更高效、更可靠。💡

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages