2026-04-14 18:07:32 +08:00
|
|
|
// 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.
|
2026-04-14 18:07:32 +08:00
|
|
|
|
2026-04-29 14:37:48 +08:00
|
|
|
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';
|
|
|
|
|
}
|
|
|
|
|
|
2026-04-14 18:07:32 +08:00
|
|
|
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;
|
2026-04-29 14:37:48 +08:00
|
|
|
size?: number;
|
|
|
|
|
graphrag_task_finish_at: string;
|
2026-04-14 18:07:32 +08:00
|
|
|
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;
|
2026-04-29 14:37:48 +08:00
|
|
|
connectors: IConnector[];
|
2026-04-14 18:07:32 +08:00
|
|
|
}
|
|
|
|
|
|
|
|
|
|
interface Parserconfig {
|
|
|
|
|
auto_keywords: number;
|
|
|
|
|
auto_questions: number;
|
|
|
|
|
children_delimiter: string;
|
|
|
|
|
chunk_token_num: number;
|
|
|
|
|
delimiter: string;
|
2026-04-29 14:37:48 +08:00
|
|
|
from_page?: number;
|
|
|
|
|
to_page?: number;
|
2026-04-14 18:07:32 +08:00
|
|
|
graphrag: Graphrag;
|
|
|
|
|
html4excel: boolean;
|
|
|
|
|
image_context_size: number;
|
|
|
|
|
layout_recognize: string;
|
|
|
|
|
llm_id: string;
|
2026-04-29 14:37:48 +08:00
|
|
|
metadata?: any;
|
|
|
|
|
built_in_metadata?: Array<{ key: string; type: string }>;
|
|
|
|
|
enable_metadata?: boolean;
|
2026-04-14 18:07:32 +08:00
|
|
|
parent_child: Parentchild;
|
|
|
|
|
raptor: Raptor;
|
|
|
|
|
table_context_size: number;
|
2026-04-29 14:37:48 +08:00
|
|
|
tag_kb_ids?: string[];
|
2026-04-14 18:07:32 +08:00
|
|
|
topn_tags: number;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
interface Raptor {
|
2026-05-11 15:42:31 -10:00
|
|
|
clustering_method?: 'gmm' | 'ahc';
|
2026-05-28 14:32:31 +08:00
|
|
|
ext?: { clustering_method: 'gmm' | 'ahc'; tree_builder: 'raptor' | 'psi' };
|
2026-04-14 18:07:32 +08:00
|
|
|
max_cluster: number;
|
|
|
|
|
max_token: number;
|
|
|
|
|
prompt: string;
|
|
|
|
|
random_seed: number;
|
|
|
|
|
threshold: number;
|
2026-05-11 15:42:31 -10:00
|
|
|
tree_builder?: 'raptor' | 'psi';
|
2026-04-14 18:07:32 +08:00
|
|
|
use_raptor: boolean;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
interface Parentchild {
|
|
|
|
|
children_delimiter: string;
|
|
|
|
|
use_parent_child: boolean;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
interface Graphrag {
|
2026-05-18 16:10:21 +08:00
|
|
|
batch_chunk_token_size?: number;
|
2026-04-14 18:07:32 +08:00
|
|
|
entity_types: string[];
|
|
|
|
|
method: string;
|
|
|
|
|
use_graphrag: boolean;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export interface IDatasetListResult {
|
|
|
|
|
kbs: IDataset[];
|
|
|
|
|
total_datasets: number;
|
|
|
|
|
}
|
2026-04-29 14:37:48 +08:00
|
|
|
|
|
|
|
|
// 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;
|
|
|
|
|
}
|