Files
ragflow/web/src/interfaces/database/dataset.ts

225 lines
5.0 KiB
TypeScript
Raw Normal View History

// for the dataset list
feat(api): add unified index API and dataset management endpoints (#14222) ### What problem does this PR solve? ## Summary Refactor the dataset API layer into a clean service/REST separation pattern, add a unified `/index` API for graph/raptor/mindmap operations, and introduce several new dataset management endpoints with full test coverage. ## Changes ### Service Layer (`dataset_api_service.py`) - Added `trace_index(dataset_id, tenant_id, index_type)` — unified trace function for all index types - Added `run_index`, `delete_index` service functions - Added `get_dataset`, `get_ingestion_summary`, `list_ingestion_logs`, `get_ingestion_log` - Added `run_embedding`, `list_tags`, `aggregate_tags`, `delete_tags`, `rename_tag` - Added `get_flattened_metadata`, `get_auto_metadata`, `update_auto_metadata` ### REST API Layer (`dataset_api.py`) **New unified routes:** | Method | Route | Description | |--------|-------|-------------| | POST | `/datasets/<id>/index?type=graph\|raptor\|mindmap` | Run index task | | GET | `/datasets/<id>/index?type=graph\|raptor\|mindmap` | Trace index task | | DELETE | `/datasets/<id>/<index_type>` | Delete index | | GET | `/datasets/<id>` | Get dataset details | | GET | `/datasets/<id>/ingestions/summary` | Ingestion summary | | GET | `/datasets/<id>/ingestions` | List ingestion logs | | GET | `/datasets/<id>/ingestions/<log_id>` | Get single ingestion log | | POST | `/datasets/<id>/embedding` | Run embedding | | GET | `/datasets/<id>/tags` | List tags | | GET | `/datasets/tags/aggregation` | Aggregate tags across datasets | | DELETE | `/datasets/<id>/tags` | Delete tags | | PUT | `/datasets/<id>/tags` | Rename tag | | GET | `/datasets/metadata/flattened` | Get flattened metadata | | GET/PUT | `/datasets/<id>/metadata/config` | New metadata config path | **Removed routes (replaced by unified `/index`):** - `POST /datasets/<id>/mindmap` - `GET /datasets/<id>/mindmap` **Preserved legacy routes (backward compatibility):** - `/run_graphrag`, `/trace_graphrag`, `/run_raptor`, `/trace_raptor` - `/auto_metadata` GET/PUT ### Test Suite - Updated `common.py` helpers: added `trace_index`, removed `run_mindmap`/`trace_mindmap` - Added 7 new test files with 39 test cases total: | Test File | Cases | |-----------|-------| | `test_get_dataset.py` | 4 | | `test_ingestion_summary.py` | 2 | | `test_ingestion_logs.py` | 5 | | `test_index_api.py` | 14 | | `test_embedding.py` | 2 | | `test_tags.py` | 8 | | `test_flattened_metadata.py` | 4 | - Deleted `test_mindmap_tasks.py` (covered by unified index tests) ## Design Decisions 1. **Unified `/index?type=...`** — single endpoint replaces 3 separate route pairs for graph/raptor/mindmap 2. **Backward compatibility** — old routes (`/run_graphrag`, `/run_raptor`, `/auto_metadata`) preserved alongside new paths 3. **`_VALID_INDEX_TYPES = {"graph", "raptor", "mindmap"}`** — input validation via constant set 4. **`_INDEX_TYPE_TO_TASK_ID_FIELD`** — maps index type to KB model task ID field for clean dispatch ## Files Changed - `api/apps/restful_apis/dataset_api.py` - `api/apps/services/dataset_api_service.py` - `sdk/python/ragflow_sdk/modules/dataset.py` - `test/testcases/test_http_api/common.py` - `test/testcases/test_http_api/test_dataset_management/` (7 new files) ### Type of change - [x] New Feature (non-breaking change which adds functionality) - [x] Refactoring --------- Signed-off-by: noob <yixiao121314@outlook.com>
2026-04-27 01:38:01 +00:00
// The data structures returned by the `datasets` interface and `/api/v1/datasets/{id}` are inconsistent.
import { RunningStatus } from '@/constants/knowledge';
import { DataSourceKey } from '@/pages/user-setting/data-source/constant';
export interface IConnector {
id: string;
name: string;
status: RunningStatus;
source: DataSourceKey;
auto_parse?: '0' | '1';
}
export interface IDataset {
avatar?: string;
chunk_count: number;
chunk_method: string;
create_date: string;
create_time: number;
created_by: string;
description?: string;
document_count: number;
embedding_model: string;
size?: number;
graphrag_task_finish_at: string;
graphrag_task_id: Nullable<string>;
id: string;
language: string;
mindmap_task_finish_at: null;
mindmap_task_id: Nullable<string>;
name: string;
nickname: string;
pagerank: number;
parser_config: Parserconfig;
permission: string;
pipeline_id: string;
raptor_task_finish_at: string;
raptor_task_id: string;
similarity_threshold: number;
status: string;
tenant_avatar: string;
tenant_embd_id: number;
tenant_id: string;
token_num: number;
update_date: string;
update_time: number;
vector_similarity_weight: number;
connectors: IConnector[];
}
interface Parserconfig {
auto_keywords: number;
auto_questions: number;
children_delimiter: string;
chunk_token_num: number;
delimiter: string;
from_page?: number;
to_page?: number;
graphrag: Graphrag;
html4excel: boolean;
image_context_size: number;
layout_recognize: string;
llm_id: string;
metadata?: any;
built_in_metadata?: Array<{ key: string; type: string }>;
enable_metadata?: boolean;
parent_child: Parentchild;
raptor: Raptor;
table_context_size: number;
tag_kb_ids?: string[];
topn_tags: number;
}
interface Raptor {
feat(raptor): add Psi tree builder with original-space ranking and safe migration (#14679) ### What problem does this PR solve? Closes #14674. This PR improves RAPTOR configuration and tree construction while preserving the existing RAPTOR behavior as the default. RAPTOR currently builds summary layers with the original UMAP + GMM clustering path. This PR keeps that default path, and adds: - A hidden backend tree-builder option: - `tree_builder="raptor"`: default, existing RAPTOR behavior. - `tree_builder="psi"`: rank-aware Psi-style tree builder using original embedding-space cosine ranking. - A user-facing clustering method option for the default RAPTOR builder: - `clustering_method="gmm"`: existing default. - `clustering_method="ahc"`: agglomerative hierarchical clustering path. - A RAPTOR UI setting for `Clustering method` and `Max cluster`. ### What changed #### Backend - Added `tree_builder` support for RAPTOR/Psi. - Added `clustering_method` support for GMM/AHC. - Kept existing RAPTOR + GMM as the default. - Added Psi tree building from original-space cosine similarity. - Added bucketed Psi building controls for large inputs: - `raptor.ext.psi_exact_max_leaves` - `raptor.ext.psi_bucket_size` - Added method-aware RAPTOR summary metadata using existing `extra.raptor_method`. - Avoided adding a dedicated DB schema field for experimental method tracking. - Added cleanup/migration logic to avoid mixing stale RAPTOR summary trees. - Added defensive checks for Psi tree construction and summary failures. #### Frontend/UI - Added `Clustering method` in RAPTOR settings with `GMM` and `AHC`. - Added/kept `Max cluster` in RAPTOR settings. - Enlarged max cluster UI limit to `1024`, matching backend validation. - Kept AHC editable even when a RAPTOR task has already finished. - Fixed the UI save payload so `clustering_method` and `tree_builder` are serialized through `parser_config.raptor.ext`, avoiding backend validation errors for extra top-level RAPTOR fields. Example saved RAPTOR config: ```json { "raptor": { "max_cluster": 317, "ext": { "clustering_method": "ahc", "tree_builder": "raptor" } } } Co-authored-by: CaptainTimon <CaptainTimon@users.noreply.github.com>
2026-05-11 15:42:31 -10:00
clustering_method?: 'gmm' | 'ahc';
ext?: { clustering_method: 'gmm' | 'ahc'; tree_builder: 'raptor' | 'psi' };
max_cluster: number;
max_token: number;
prompt: string;
random_seed: number;
threshold: number;
feat(raptor): add Psi tree builder with original-space ranking and safe migration (#14679) ### What problem does this PR solve? Closes #14674. This PR improves RAPTOR configuration and tree construction while preserving the existing RAPTOR behavior as the default. RAPTOR currently builds summary layers with the original UMAP + GMM clustering path. This PR keeps that default path, and adds: - A hidden backend tree-builder option: - `tree_builder="raptor"`: default, existing RAPTOR behavior. - `tree_builder="psi"`: rank-aware Psi-style tree builder using original embedding-space cosine ranking. - A user-facing clustering method option for the default RAPTOR builder: - `clustering_method="gmm"`: existing default. - `clustering_method="ahc"`: agglomerative hierarchical clustering path. - A RAPTOR UI setting for `Clustering method` and `Max cluster`. ### What changed #### Backend - Added `tree_builder` support for RAPTOR/Psi. - Added `clustering_method` support for GMM/AHC. - Kept existing RAPTOR + GMM as the default. - Added Psi tree building from original-space cosine similarity. - Added bucketed Psi building controls for large inputs: - `raptor.ext.psi_exact_max_leaves` - `raptor.ext.psi_bucket_size` - Added method-aware RAPTOR summary metadata using existing `extra.raptor_method`. - Avoided adding a dedicated DB schema field for experimental method tracking. - Added cleanup/migration logic to avoid mixing stale RAPTOR summary trees. - Added defensive checks for Psi tree construction and summary failures. #### Frontend/UI - Added `Clustering method` in RAPTOR settings with `GMM` and `AHC`. - Added/kept `Max cluster` in RAPTOR settings. - Enlarged max cluster UI limit to `1024`, matching backend validation. - Kept AHC editable even when a RAPTOR task has already finished. - Fixed the UI save payload so `clustering_method` and `tree_builder` are serialized through `parser_config.raptor.ext`, avoiding backend validation errors for extra top-level RAPTOR fields. Example saved RAPTOR config: ```json { "raptor": { "max_cluster": 317, "ext": { "clustering_method": "ahc", "tree_builder": "raptor" } } } Co-authored-by: CaptainTimon <CaptainTimon@users.noreply.github.com>
2026-05-11 15:42:31 -10:00
tree_builder?: 'raptor' | 'psi';
use_raptor: boolean;
}
interface Parentchild {
children_delimiter: string;
use_parent_child: boolean;
}
interface Graphrag {
batch_chunk_token_size?: number;
entity_types: string[];
method: string;
use_graphrag: boolean;
}
export interface IDatasetListResult {
kbs: IDataset[];
total_datasets: number;
}
// Types migrated from knowledge.ts
export interface IKnowledgeFileParserConfig {
chunk_token_num: number;
layout_recognize: boolean;
pages: number[][];
task_page_size: number;
}
export interface IKnowledgeFile {
chunk_num: number;
create_date: string;
create_time: number;
created_by: string;
id: string;
kb_id: string;
location: string;
name: string;
parser_id: string;
process_begin_at?: any;
process_duration: number;
progress: number; // parsing process
progress_msg: string; // parsing log
run: RunningStatus; // parsing status
size: number;
source_type: string;
status: string; // enabled
thumbnail?: any; // base64
token_num: number;
type: string;
update_date: string;
update_time: number;
parser_config: IKnowledgeFileParserConfig;
}
export interface ITenantInfo {
asr_id: string;
embd_id: string;
img2txt_id: string;
llm_id: string;
name: string;
parser_ids: string;
role: string;
tenant_id: string;
chat_id: string;
speech2text_id: string;
rerank_id?: string;
tts_id: string;
// Tenant model IDs
tenant_asr_id?: string;
tenant_embd_id?: string;
tenant_img2txt_id?: string;
tenant_llm_id?: string;
tenant_rerank_id?: string;
tenant_tts_id?: string;
}
export type ChunkDocType = 'image' | 'table' | 'text';
export interface IChunk {
available_int: number; // Whether to enable, 0: not enabled, 1: enabled
chunk_id: string;
content_with_weight: string;
doc_id: string;
doc_name: string;
doc_type_kwd?: ChunkDocType;
image_id: string;
important_kwd?: string[];
question_kwd?: string[]; // keywords
tag_kwd?: string[];
positions: number[][];
tag_feas?: Record<string, number>;
}
export interface ITestingChunk {
chunk_id: string;
content_ltks: string;
content_with_weight: string;
doc_id: string;
doc_name: string;
img_id: string;
image_id: string;
important_kwd: any[];
kb_id: string;
similarity: number;
term_similarity: number;
vector: number[];
vector_similarity: number;
highlight: string;
positions: number[][];
docnm_kwd: string;
doc_type_kwd: string;
}
export interface ITestingDocument {
count: number;
doc_id: string;
doc_name: string;
}
export interface ITestingResult {
chunks: ITestingChunk[];
documents: ITestingDocument[];
total: number;
labels?: Record<string, number>;
}
export interface INextTestingResult {
chunks: ITestingChunk[];
doc_aggs: ITestingDocument[];
total: number;
labels?: Record<string, number>;
isRuned?: boolean;
}
export type IRenameTag = { fromTag: string; toTag: string };
export interface IKnowledgeGraph {
graph: Record<string, any>;
mind_map: import('@antv/g6/lib/types').TreeData;
}