INIS 分类与叙词服务文档总览

脱敏说明：本文档中的用户目录、内网地址、数据集标识、API Key 与默认密钥均已替换为占位符，例如 <project-root>、<weaviate-url>、<api-key>。

中英文名称

• 中文名称：INIS 分类与叙词服务
• English Name: INIS Classification and Thesaurus Service

一句话介绍

这是一个基于 Django、LangGraph 与 Weaviate 的文献处理系统，用于完成 INIS 叙词匹配、分类推荐、流程追踪与知识库增强检索。

项目展示

系统概览

应用中心

工作流示意

目录

文档导航

文档	说明
src/api.md	REST API 入口、接口职责与返回模式
src/apps.md	apps 业务模块聚合说明
src/bocha_search.md	联网搜索增强模块
src/core.md	数据模型、序列化器、后台与任务记录
src/data_import.md	INIS 数据导入链路
src/database_query.md	关系型查询与匹配策略
src/docker.md	Docker 与本地依赖服务
src/inis_800.md	Django 项目配置与全局设置
src/langgraph_workflow.md	工作流编排与节点结构
src/llm.md	大模型客户端抽象
src/ragflow.md	RAGFlow 知识库检索集成
src/weaviate.md	Weaviate Schema、查询与迁移

项目结构

<project-root>/
├── api/
├── apps/
│   ├── bocha_search/
│   ├── core/
│   ├── database_query/
│   ├── data_import/
│   ├── langgraph_workflow/
│   ├── llm/
│   ├── ragflow/
│   └── weaviate/
├── docker/
├── inis_800/
├── manage.py
├── requirements.txt
└── start-dev.sh

配置

核心环境变量

配置项	用途	示例占位值
DEBUG	Django 调试模式	True
ALLOWED_HOSTS	服务白名单	localhost,127.0.0.1
USE_POSTGRESQL	是否切换 PostgreSQL	False
WEAVIATE_URL	Weaviate 服务地址	http://<weaviate-host>:8080
VOLCANO_API_BASE	火山引擎兼容接口地址	https://<llm-endpoint>/api/v3
VOLCANO_API_KEY	火山引擎密钥	<api-key>
DASHSCOPE_API_KEY	备用模型密钥	<api-key>
RAGFLOW_API_BASE	RAGFlow 服务地址	http://<ragflow-host>:<port>
RAGFLOW_API_KEY	RAGFlow 密钥	<api-key>
RAGFLOW_DATASET_IDS	默认知识库数据集	<dataset-id-1>,<dataset-id-2>
BOCHA_API_URL	博查搜索接口地址	https://<search-endpoint>/v1/ai-search
BOCHA_API_KEY	博查搜索密钥	<api-key>
ENABLE_ONLINE_SEARCH	是否启用联网搜索增强	False

配置建议

场景	建议
本地开发	默认使用 SQLite + 本地 Weaviate，先保证流程跑通
小规模联调	打开 ENABLE_ONLINE_SEARCH，并为 LLM 与检索服务配置真实密钥
稳定部署	将所有默认密钥迁出代码，统一改为 .env 或密钥管理服务注入

核心特色

• 支持两条主流程：叙词匹配 与 分类工作流。
• 叙词匹配流程带有多层兜底：节点异常、叙词不足 3 个、API 返回兜底。
• 查询策略同时覆盖关系型数据库、Weaviate、RAGFlow 与联网搜索增强。
• 所有关键步骤都可落库记录，便于问题回放、审计与质量分析。
• 项目保留 SQLite 开发路径，也支持切换 PostgreSQL。

工具概览

工具/框架	角色	在项目中的位置
Django 4.2	Web 框架与 ORM	inis_800/, apps/core/
Django REST Framework	API 输出与序列化	api/, apps/core/serializers.py
LangGraph	工作流编排	apps/langgraph_workflow/
Weaviate v3 Client	叙词检索与关系增强	apps/weaviate/
火山引擎 Ark SDK	主 LLM 客户端	apps/llm/client.py
DashScope	备用 LLM 通道	apps/llm/client.py
Requests	外部服务调用	apps/ragflow/, apps/bocha_search/
Docker Compose	本地依赖启动	docker/

技术亮点

1. 双工作流架构

• run_workflow(...) 负责叙词提取与 800 字段输出。
• run_classification_workflow(...) 负责一级分类候选、二三级细分与结果汇总。

2. 强兜底策略

• 叙词流程末端存在 thesaurus_count_guard 节点。
• API 层对少于 3 个叙词的场景统一返回默认格式化结果。
• LangGraph stream 执行时可识别失败节点，并尝试从已有 matched_terms 继续收敛结果。

3. 多源检索融合

• 关系型查询适合精确匹配、同义词、上下位词、相关词规则。
• Weaviate 适合结构化术语检索与类 Schema 管理。
• RAGFlow 用于知识库片段召回与术语提取。
• 博查搜索负责开放网络增强，补齐知识库外部语义。

4. 可观测性设计

• 匹配任务、分类任务、步骤日志均可持久化。
• 工作流状态结构显式定义，便于调试、补偿与接口回放。

快速开始

cd <project-root>
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # 如果仓库提供该文件

cd <project-root>/docker
./dev-start.sh

cd <project-root>
python manage.py migrate
python manage.py import_inis_data \
  --cterms <cterms-json> \
  --relations <relations-json> \
  --relation-note <relation-note-json>
./start-dev.sh

本地部署

部署流程

flowchart LR
    A[Client / Test Script] --> B[Django API]
    B --> C[LangGraph Workflow]
    C --> D[LLM Client]
    C --> E[Weaviate]
    C --> F[RAGFlow]
    C --> G[Bocha Search]
    B --> H[(SQLite / PostgreSQL)]

Loading

部署建议

1. 先启动 docker/dev-start.sh 提供 Weaviate。
2. 再执行 Django 迁移与数据导入。
3. 最后启动 ./start-dev.sh 或 python manage.py runserver。
4. 联调接口时优先验证：
   • POST /api/v1/thesaurus/match/
   • POST /api/v1/classification/tasks/

常用验证命令

python test_validation.py --count 10
python test_thesaurus_api.py --api http://localhost:8000 --limit 20
python test_classification_api.py --api http://localhost:8000 --limit 20

许可证

仓库中未发现独立的 LICENSE 文件。若该项目用于团队共享、交付或对外发布，建议补充明确的许可证或内部使用声明；在当前状态下，更适合按“未公开授权的内部项目”理解。