TanWenyan/leaudit-platform-frontend

Fork 0

Files

T

PingChuan 0f49426a2e feat：完成上传文档时调整嵌入参数模块初版

2025-12-02 22:29:32 +08:00

24 KiB

Raw Blame History

Dify 知识库 API 功能实现清单

概述

本文档对比 Dify 官方知识库 API 与当前项目已实现的功能。

✅ 已实现
❌ 未实现
🚫 不开放

系统架构

完整数据流向

┌─────────────────────────────────────────────────────────────────────┐
│  第一层：React 组件 (浏览器)                                         │
│  位置：app/components/dify-dataset-manager/                         │
│  调用：客户端 API 函数                                               │
└────────────────────────────┬────────────────────────────────────────┘
                              │ 使用 axios 发送 HTTP 请求
                              │ URL: /api/dataset/...
                              │ 自动携带 cookies (JWT)
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│  第二层：客户端 API 层 (浏览器侧)                                    │
│  位置：app/api/dify-dataset/api/*.ts                                │
│  作用：封装 axios 请求，提供类型安全的函数接口                        │
│  请求：axios.get('/api/dataset/datasets', { withCredentials: true })│
└────────────────────────────┬────────────────────────────────────────┘
                              │ HTTP 请求 (浏览器 → Remix 服务器)
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│  第三层：Remix 路由层 (Node.js 服务端)                               │
│  位置：app/routes/api.dataset.*.tsx                                 │
│  作用：接收浏览器请求，验证 JWT，转发到 FastAPI                      │
│  请求：fetch(`${API_BASE_URL}/dify_dataset/...`, { headers: JWT })  │
└────────────────────────────┬────────────────────────────────────────┘
                              │ HTTP 请求 (Remix → FastAPI)
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│  第四层：FastAPI 后端代理 (Python)                                   │
│  位置：docauditai/routers/dify_dataset.py                           │
│  作用：验证用户 JWT，添加 Dify DATASET_API_KEY，转发请求             │
└────────────────────────────┬────────────────────────────────────────┘
                              │ HTTP 请求 (FastAPI → Dify)
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│  第五层：Dify 官方知识库 API                                         │
│  URL：https://api.dify.ai/v1/datasets/...                           │
│  鉴权：Authorization: Bearer {DATASET_API_KEY}                      │
└─────────────────────────────────────────────────────────────────────┘

为什么有两层 API？

层级	位置	执行环境	HTTP 库	作用
客户端 API	`app/api/dify-dataset/api/*.ts`	浏览器	axios	供 React 组件调用，类型安全
Remix 路由	`app/routes/api.dataset.*.tsx`	Node.js	fetch	接收浏览器请求，转发到 FastAPI

调用链路：

React 组件 → 客户端 API (axios) → Remix 路由 (fetch) → FastAPI → Dify API

一、知识库管理

功能	API 端点	方法	状态	路由文件	客户端函数
获取知识库列表	/datasets	GET	✅	`api.dataset.datasets.tsx`	`fetchDatasets()`
查看知识库详情	/datasets/{dataset_id}	GET	✅	`api.dataset.datasets.$datasetId.tsx`	`fetchDataset()`
创建空知识库	/datasets	POST	❌	-	-
修改知识库名称	/datasets/{dataset_id}	PATCH	✅	`api.dataset.datasets.$datasetId.tsx`	`updateDatasetName()`
删除知识库	/datasets/{dataset_id}	DELETE	🚫	-	-

说明：

修改知识库：仅允许修改 name 字段，其他字段不开放
删除知识库：出于安全考虑不对用户开放

二、文档管理

功能	API 端点	方法	状态	路由文件	客户端函数
获取文档列表	/datasets/{id}/documents	GET	✅	`api.dataset.datasets.$datasetId.documents.tsx`	`fetchDocuments()`
获取文档详情	/datasets/{id}/documents/{docId}	GET	✅	`api.dataset.datasets.$datasetId.documents.$documentId.tsx`	`fetchDocument()`
通过文件创建文档	/datasets/{id}/document/create-by-file	POST	✅	`api.dataset.datasets.$datasetId.documents.tsx`	`uploadDocument()`
通过文本创建文档	/datasets/{id}/document/create-by-text	POST	❌	-	-
通过文件更新文档	/datasets/{id}/documents/{docId}/update-by-file	POST	❌	-	-
通过文本更新文档	/datasets/{id}/documents/{docId}/update-by-text	POST	❌	-	-
删除文档	/datasets/{id}/documents/{docId}	DELETE	✅	`api.dataset.datasets.$datasetId.documents.$documentId.tsx`	`deleteDocument()`
更新文档状态	/datasets/{id}/documents/status/{action}	PATCH	✅	`api.dataset.datasets.$datasetId.documents.status.$action.tsx`	`toggleDocumentStatus()`
获取文档嵌入状态	/datasets/{id}/documents/{batch}/indexing-status	GET	✅	`api.dataset.datasets.$datasetId.documents.$batch.indexing-status.tsx`	`fetchIndexingStatus()`
获取上传文件信息	/datasets/{id}/documents/{docId}/upload-file	GET	✅	`api.dataset.datasets.$datasetId.documents.$documentId.upload-file.tsx`	`fetchUploadFileInfo()`
索引预估（预览分段）	/datasets/{id}/indexing-estimate	POST	✅	`api.dataset.datasets.$datasetId.indexing-estimate.tsx`	`fetchIndexingEstimate()`
重新处理文档	/datasets/{id}/documents/reprocess	POST	✅	`api.dataset.datasets.$datasetId.documents.reprocess.tsx`	`reprocessDocument()`

说明：

上传文档：支持 multipart/form-data 格式
文档状态：action 可选值为 enable / disable / archive / un_archive
索引预估：用于预览分段效果，不会实际修改文档
重新处理文档：通过 original_document_id 参数使用新的分段设置重新处理已有文档

三、分段管理

功能	API 端点	方法	状态	路由文件	客户端函数
获取分段列表	/datasets/{id}/documents/{docId}/segments	GET	✅	`api.dataset.datasets.$datasetId.documents.$documentId.segments.tsx`	`fetchSegments()`
获取分段详情	/datasets/{id}/documents/{docId}/segments/{segId}	GET	✅	`api.dataset.datasets.$datasetId.documents.$documentId.segments.$segmentId.tsx`	`fetchSegment()`
新增分段	/datasets/{id}/documents/{docId}/segments	POST	✅	`api.dataset.datasets.$datasetId.documents.$documentId.segments.tsx`	`createSegments()`
更新分段	/datasets/{id}/documents/{docId}/segments/{segId}	POST	✅	`api.dataset.datasets.$datasetId.documents.$documentId.segments.$segmentId.tsx`	`updateSegment()`
删除分段	/datasets/{id}/documents/{docId}/segments/{segId}	DELETE	✅	`api.dataset.datasets.$datasetId.documents.$documentId.segments.$segmentId.tsx`	`deleteSegment()`

说明：

新增分段：支持批量新增 { segments: [...] }
更新分段：可更新 content, answer, keywords, enabled

四、子分段管理（父子模式）

功能	API 端点	方法	状态	路由文件	客户端函数
查询子分段	.../segments/{segId}/child_chunks	GET	✅	`...segments.$segmentId.child_chunks.tsx`	`fetchChildChunks()`
新增子分段	.../segments/{segId}/child_chunks	POST	✅	`...segments.$segmentId.child_chunks.tsx`	`createChildChunk()`
更新子分段	.../segments/{segId}/child_chunks/{chunkId}	PATCH	✅	`...segments.$segmentId.child_chunks.$childChunkId.tsx`	`updateChildChunk()`
删除子分段	.../segments/{segId}/child_chunks/{chunkId}	DELETE	✅	`...segments.$segmentId.child_chunks.$childChunkId.tsx`	`deleteChildChunk()`

说明：子分段用于 Dify 的父子模式分段策略

五、检索功能

功能	API 端点	方法	状态	路由文件	客户端函数
检索知识库	/datasets/{id}/retrieve	POST	✅	`api.dataset.datasets.$datasetId.retrieve.tsx`	`retrieveDataset()`

检索参数详解：

{
  query: string;                    // 检索关键词
  retrieval_model: {
    search_method: 'keyword_search' | 'semantic_search' | 'full_text_search' | 'hybrid_search';
    reranking_enable: boolean;      // 是否开启 rerank
    reranking_model?: object;       // Rerank 模型配置
    top_k: number;                  // 返回结果数量
    score_threshold_enabled: boolean;
    score_threshold: number;        // 分数阈值 (0-1)
  }
}

六、元数据管理

当前状态：❌ 全部未实现

功能	API 端点	方法	说明
新增元数据	/datasets/{id}/metadata	POST	type, name
更新元数据	/datasets/{id}/metadata/{metaId}	PATCH	name
删除元数据	/datasets/{id}/metadata/{metaId}	DELETE
查询元数据列表	/datasets/{id}/metadata	GET
启用/禁用内置元数据	/datasets/{id}/metadata/built-in/{action}	POST
更新文档元数据	/datasets/{id}/documents/metadata	POST	批量更新

七、模型查询

功能	API 端点	方法	状态	说明
获取嵌入模型列表	/workspaces/current/models/model-types/text-embedding	GET	❌	创建知识库时需要

八、标签管理

当前状态：❌ 全部未实现

功能	API 端点	方法	说明
新增标签	/datasets/tags	POST	name (最大50字符)
获取标签列表	/datasets/tags	GET
修改标签名称	/datasets/tags	PATCH	name, tag_id
删除标签	/datasets/tags	DELETE	tag_id
绑定知识库到标签	/datasets/tags/binding	POST	tag_ids, target_id
解绑知识库和标签	/datasets/tags/unbinding	POST	tag_id, target_id
查询知识库已绑定的标签	/datasets/{id}/tags	POST

功能统计

类别	已实现	未实现	不开放	完成度
知识库管理	3	1	1	75%
文档管理	9	3	0	75%
分段管理	5	0	0	100%
子分段管理	4	0	0	100%
检索功能	1	0	0	100%
元数据管理	0	6	0	0%
模型查询	0	1	0	0%
标签管理	0	7	0	0%
总计	22	18	1	55%

代码文件清单

Remix 路由层 (服务端)

所有路由文件位于 app/routes/ 目录：

文件名	HTTP 方法	功能
`api.dataset.datasets.tsx`	GET	获取知识库列表
`api.dataset.datasets.$datasetId.tsx`	GET / PATCH	知识库详情 / 修改名称
`api.dataset.datasets.$datasetId.documents.tsx`	GET / POST	文档列表 / 上传文档
`api.dataset.datasets.$datasetId.documents.$documentId.tsx`	GET / DELETE	文档详情 / 删除文档
`api.dataset.datasets.$datasetId.documents.$documentId.upload-file.tsx`	GET	获取上传文件信息
`api.dataset.datasets.$datasetId.documents.$batch.indexing-status.tsx`	GET	获取嵌入状态
`api.dataset.datasets.$datasetId.documents.status.$action.tsx`	PATCH	更新文档状态
`api.dataset.datasets.$datasetId.indexing-estimate.tsx`	POST	索引预估（预览分段）
`api.dataset.datasets.$datasetId.documents.reprocess.tsx`	POST	重新处理文档
`api.dataset.datasets.$datasetId.documents.$documentId.segments.tsx`	GET / POST	分段列表 / 新增分段
`api.dataset.datasets.$datasetId.documents.$documentId.segments.$segmentId.tsx`	GET / POST / DELETE	分段详情 / 更新 / 删除
`api.dataset.datasets.$datasetId.documents.$documentId.segments.$segmentId.child_chunks.tsx`	GET / POST	子分段列表 / 新增
`api.dataset.datasets.$datasetId.documents.$documentId.segments.$segmentId.child_chunks.$childChunkId.tsx`	PATCH / DELETE	子分段更新 / 删除
`api.dataset.datasets.$datasetId.retrieve.tsx`	POST	检索知识库

客户端 API 层 (浏览器侧)

app/api/dify-dataset/
├── index.ts                    # 统一导出
├── client.server.ts            # 服务端基础请求函数（备用）
├── type/                       # 类型定义
│   ├── index.ts               # 类型统一导出
│   ├── commonTypes.ts         # 通用类型
│   ├── datasetTypes.ts        # 知识库类型
│   ├── documentTypes.ts       # 文档类型
│   └── segmentTypes.ts        # 分段/子分段/检索类型
└── api/                        # API 调用函数
    ├── index.ts               # 函数统一导出
    ├── datasetApi.ts          # 知识库 API
    ├── documentApi.ts         # 文档 API
    └── segmentApi.ts          # 分段/子分段/检索 API

客户端函数清单

datasetApi.ts - 知识库管理

fetchDatasets(page, limit)            // 获取知识库列表
fetchDataset(datasetId)               // 获取知识库详情
updateDatasetName(datasetId, name)    // 修改知识库名称

documentApi.ts - 文档管理

fetchDocuments(datasetId, page, limit, keyword)       // 获取文档列表
fetchDocument(datasetId, documentId)                   // 获取文档详情
deleteDocument(datasetId, documentId)                  // 删除文档
toggleDocumentStatus(datasetId, documentId, enabled)   // 启用/禁用文档
uploadDocument(datasetId, file, onProgress)            // 上传文档
fetchIndexingStatus(datasetId, batch)                  // 获取嵌入状态
fetchUploadFileInfo(datasetId, documentId)             // 获取上传文件信息
fetchIndexingEstimate(datasetId, fileId, processRule, docForm, docLanguage)  // 索引预估（预览分段效果）
reprocessDocument(datasetId, originalDocumentId, processRule, docForm, docLanguage) // 重新处理文档

segmentApi.ts - 分段/子分段/检索

// 分段
fetchSegments(datasetId, documentId, page, limit, keyword)
fetchSegment(datasetId, documentId, segmentId)
createSegments(datasetId, documentId, segments)
updateSegment(datasetId, documentId, segmentId, segment)
deleteSegment(datasetId, documentId, segmentId)
toggleSegmentStatus(datasetId, documentId, segmentId, enabled)

// 子分段
fetchChildChunks(datasetId, documentId, segmentId, page, limit, keyword)
createChildChunk(datasetId, documentId, segmentId, content)
updateChildChunk(datasetId, documentId, segmentId, childChunkId, content)
deleteChildChunk(datasetId, documentId, segmentId, childChunkId)

// 检索
retrieveDataset(datasetId, query, retrievalModel)

UI 组件

app/components/dify-dataset-manager/
├── index.tsx              # 主容器组件 - 状态管理、标签页切换
├── layout.tsx             # 布局组件 - 左侧菜单栏 + 右侧内容区
├── document-list.tsx      # 文档列表 - 表格、搜索、上传、删除
├── document-detail.tsx    # 文档详情 - 分段设置、预览块
├── retrieve-test.tsx      # 召回测试 - 知识库检索测试
└── dataset-settings.tsx   # 知识库设置 - 名称、描述修改

布局结构（仿 Dify 风格）

┌─────────────────────────────────────────────────────────────┐
│                   dataset-layout                            │
├──────────────────┬──────────────────────────────────────────┤
│   dataset-sidebar │             dataset-main               │
│                   │                                         │
│  ┌─────────────┐ │  根据 activeTab 渲染：                   │
│  │ 知识库信息  │ │  - documents → DocumentList              │
│  │ (名称/数量) │ │  - documents + selectedDoc → DocumentDetail│
│  └─────────────┘ │  - retrieve → RetrieveTest              │
│                   │  - settings → DatasetSettings           │
│  ┌─────────────┐ │                                         │
│  │ 文档        │ │                                         │
│  │ 召回测试    │ │                                         │
│  │ 设置        │ │                                         │
│  └─────────────┘ │                                         │
└──────────────────┴──────────────────────────────────────────┘

鉴权机制

三层认证流程

┌────────────────────────────────────────────────────────────────┐
│ 浏览器 → Remix 服务器                                          │
│ 认证方式：Cookie (会话中的 JWT)                                │
│ axios 配置：{ withCredentials: true }                         │
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│ Remix 服务器 → FastAPI                                        │
│ 认证方式：Authorization: Bearer {frontendJWT}                 │
│ JWT 来源：getUserSession(request)                             │
└────────────────────────────────────────────────────────────────┘
                              ↓
┌────────────────────────────────────────────────────────────────┐
│ FastAPI → Dify API                                            │
│ 认证方式：Authorization: Bearer {DATASET_API_KEY}             │
│ API Key：服务端环境变量配置                                    │
└────────────────────────────────────────────────────────────────┘

关键配置

// app/config/api-config.ts
export const API_BASE_URL = apiConfig.baseUrl;  // 如：http://10.79.97.17:8000

// 根据端口自动选择配置
const portConfigs = {
  '51703': { baseUrl: 'http://172.16.0.55:8073' },  // 梅州
  '51704': { baseUrl: 'http://10.79.97.17:8001' },  // 云浮
  '51707': { baseUrl: 'http://10.79.97.17:8004' },  // 省级
  // ...
};

常见错误码

code	status	message
no_file_uploaded	400	Please upload your file.
too_many_files	400	Only one file is allowed.
file_too_large	413	File size exceeded.
unsupported_file_type	415	File type not allowed.
high_quality_dataset_only	400	Current operation only supports 'high-quality' datasets.
dataset_not_initialized	400	The dataset is still being initialized or indexing.
archived_document_immutable	403	The archived document is not editable.
dataset_name_duplicate	409	The dataset name already exists.
invalid_action	400	Invalid action.
document_already_finished	400	The document has been processed.
document_indexing	400	The document is being processed and cannot be edited.
invalid_metadata	400	The metadata content is incorrect.

九、文档分段设置（上传时配置）

API 支持的分段参数

在上传文档时，可以通过 process_rule 参数配置分段设置：

{
  indexing_technique: 'high_quality' | 'economy',
  process_rule: {
    mode: 'automatic' | 'custom',
    rules: {
      pre_processing_rules: [
        { id: 'remove_extra_spaces', enabled: boolean },  // 替换连续空格
        { id: 'remove_urls_emails', enabled: boolean }    // 删除URL和邮件
      ],
      segmentation: {
        separator: string,    // 分段标识符，如 "\\n\\n"
        max_tokens: number    // 分段最大长度，100-4000
      }
    }
  }
}

功能支持情况

功能	API 支持	参数	说明
分段标识符	✅	`separator`	如 `\\n\\n`、`###`
分段最大长度	✅	`max_tokens`	100-4000
替换连续空格	✅	`remove_extra_spaces`	预处理规则
删除URL和邮件	✅	`remove_urls_emails`	预处理规则
分段重叠长度	❌	-	API 不支持
Q&A 分段	⚠️	`doc_form: "qa_model"`	需特殊配置

重要限制

⚠️ 已有文档无法直接修改分段设置

Dify API 不支持修改已上传文档的分段规则。如需应用新设置，必须：

使用 original_document_id 参数重新上传文档
或删除文档后重新上传

优先级建议

高优先级（核心功能）

~~检索知识库~~ ✅ 已实现
~~获取文档嵌入状态~~ ✅ 已实现
创建空知识库 - 让用户能创建新的知识库
获取嵌入模型列表 - 创建知识库时需要选择模型

中优先级（完善功能）

通过文本创建文档 - 支持直接输入文本
~~新增分段~~ ✅ 已实现
~~修改知识库详情~~ ✅ 已实现
~~获取上传文件信息~~ ✅ 已实现

低优先级（扩展功能）

~~子分段管理系列~~ ✅ 已实现（API层）
元数据管理系列
标签管理系列
文档更新功能

24 KiB Raw Blame History Unescape Escape