Files

guangfei.zhao fe8747983e feat(knowledge): add configuration components and refactor general form

feat(hooks): add llm-related hooks and constants
docs: add architecture analysis for reference projects

2025-10-15 16:24:53 +08:00

7.9 KiB

Raw Blame History

参考Setting项目架构分析

项目概述

参考项目位于 rag_web_core/src/pages/dataset/setting，采用了基于 react-hook-form 和 zod 的现代表单管理架构，实现了高度模块化和可扩展的配置页面。

文件结构

setting/
├── index.tsx                           # 主页面入口
├── form-schema.ts                      # 表单数据结构定义
├── general-form.tsx                    # 通用表单组件
├── chunk-method-form.tsx               # 动态解析方法表单
├── configuration-form-container.tsx    # 表单容器组件
├── hooks.ts                           # 数据获取和状态管理
├── saving-button.tsx                  # 保存按钮组件
├── permission-form-field.tsx          # 权限表单字段
├── tag-item.tsx                       # 标签项组件
├── configuration/                      # 配置组件目录
│   ├── common-item.tsx                # 通用配置项
│   ├── naive.tsx                      # 通用解析配置
│   ├── qa.tsx                         # Q&A解析配置
│   ├── paper.tsx                      # 论文解析配置
│   ├── book.tsx                       # 书籍解析配置
│   ├── table.tsx                      # 表格解析配置
│   ├── audio.tsx                      # 音频解析配置
│   ├── email.tsx                      # 邮件解析配置
│   ├── laws.tsx                       # 法律解析配置
│   ├── manual.tsx                     # 手册解析配置
│   ├── one.tsx                        # One解析配置
│   ├── picture.tsx                    # 图片解析配置
│   ├── presentation.tsx               # 演示文稿解析配置
│   ├── resume.tsx                     # 简历解析配置
│   ├── knowledge-graph.tsx            # 知识图谱配置
│   └── tag.tsx                        # 标签配置
└── tag-table/                         # 标签表格相关组件
    └── ...

核心架构模式

1. 主从架构模式 (Master-Slave)

主控制器: index.tsx 作为主页面，管理整体状态和表单实例
从组件: general-form.tsx 和 chunk-method-form.tsx 作为子表单组件

2. 策略模式 (Strategy Pattern)

配置映射: ConfigurationComponentMap 根据 parser_id 动态选择配置组件
组件策略: 每个解析类型对应一个独立的配置组件

3. 模块化设计

功能分离: 通用配置与特定解析配置分离
组件复用: 通过 configuration-form-container.tsx 提供统一的布局容器

关键技术实现

1. 表单管理系统

数据结构 (form-schema.ts)

export const formSchema = z.object({
  name: z.string().min(1),
  description: z.string().min(2),
  avatar: z.any().nullish(),
  permission: z.string().optional(),
  parser_id: z.string(),
  embd_id: z.string(),
  parser_config: z.object({
    layout_recognize: z.string(),
    chunk_token_num: z.number(),
    delimiter: z.string(),
    auto_keywords: z.number().optional(),
    auto_questions: z.number().optional(),
    html4excel: z.boolean(),
    raptor: z.object({...}),
    graphrag: z.object({...}),
  }).optional(),
  pagerank: z.number(),
});

表单初始化

const form = useForm<z.infer<typeof formSchema>>({
  resolver: zodResolver(formSchema),
  defaultValues: {
    name: '',
    parser_id: DocumentParserType.Naive,
    permission: PermissionRole.Me,
    parser_config: {
      layout_recognize: DocumentType.DeepDOC,
      chunk_token_num: 512,
      delimiter: `\n`,
      // ... 其他默认值
    },
  },
});

2. 动态表单系统

配置组件映射

const ConfigurationComponentMap = {
  [DocumentParserType.Naive]: NaiveConfiguration,
  [DocumentParserType.Qa]: QAConfiguration,
  [DocumentParserType.Resume]: ResumeConfiguration,
  // ... 其他映射
};

动态组件渲染

const ConfigurationComponent = useMemo(() => {
  return finalParserId
    ? ConfigurationComponentMap[finalParserId]
    : EmptyComponent;
}, [finalParserId]);

3. 状态管理

表单上下文共享

使用 useFormContext() 在子组件中访问表单实例
通过 useWatch() 监听特定字段变化

数据获取钩子

// hooks.ts
export function useFetchKnowledgeConfigurationOnMount(form) {
  // 获取知识库配置并初始化表单
}

4. 页面布局结构

主页面布局 (index.tsx)

<section className="p-5 h-full flex flex-col">
  <TopTitle />
  <div className="flex gap-14 flex-1 min-h-0">
    <Form {...form}>
      <form className="space-y-6 flex-1">
        <Tabs>
          <TabsList>
            <TabsTrigger value="generalForm">通用</TabsTrigger>
            <TabsTrigger value="chunkMethodForm">解析方法</TabsTrigger>
          </TabsList>
          <TabsContent value="generalForm">
            <GeneralForm />
          </TabsContent>
          <TabsContent value="chunkMethodForm">
            <ChunkMethodForm />
          </TabsContent>
        </Tabs>
      </form>
    </Form>
    <ChunkMethodLearnMore />
  </div>
</section>

表单容器组件

// configuration-form-container.tsx
export function ConfigurationFormContainer({ children, className }) {
  return (
    <FormContainer className={cn('p-10', className)}>
      {children}
    </FormContainer>
  );
}

export function MainContainer({ children }) {
  return <section className="space-y-5">{children}</section>;
}

组件设计模式

1. 通用表单组件 (general-form.tsx)

使用 FormField 组件统一表单字段样式
采用 1/4 和 3/4 的标签与输入框布局比例
集成头像上传、权限选择等通用功能

2. 配置组件模式

每个配置组件遵循统一的结构：

export function NaiveConfiguration() {
  return (
    <ConfigurationFormContainer>
      <MainContainer>
        <LayoutRecognizeFormField />
        <MaxTokenNumberFormField />
        <DelimiterFormField />
        <AutoKeywordsFormField />
        <AutoQuestionsFormField />
        <TagItems />
      </MainContainer>
    </ConfigurationFormContainer>
  );
}

3. 表单字段组件

统一的 FormField 包装器
一致的错误处理和验证显示
响应式布局设计

技术特色

1. 类型安全

使用 TypeScript 和 Zod 确保类型安全
表单数据结构与后端API对齐

2. 性能优化

使用 useMemo 优化动态组件渲染
useWatch 精确监听字段变化，避免不必要的重渲染

3. 可扩展性

新增解析类型只需添加配置组件和映射关系
模块化设计便于功能扩展

4. 用户体验

Tab切换提供清晰的功能分区
右侧学习面板提供上下文帮助
统一的保存和重置操作

与用户项目的对比

用户当前架构

使用 Material-UI 组件库
基于 react-hook-form 但结构相对简单
单一的 Accordion 布局
配置逻辑集中在一个组件中

参考项目优势

更清晰的模块化分离
动态配置组件系统
更好的代码组织和可维护性
统一的设计语言和布局模式

适配建议

1. 保持现有样式

继续使用 Material-UI 组件
保持 Accordion 布局风格
适配现有的主题和设计规范

2. 采用核心架构

引入动态配置组件映射机制
分离通用配置和特定解析配置
使用 useFormContext 实现组件间状态共享

3. 数据结构对齐

参考 form-schema.ts 调整数据结构
使用 Zod 进行数据验证
统一默认值设置

4. 状态管理优化

使用 useWatch 监听字段变化
实现数据获取钩子
优化表单重置和提交逻辑

这种架构设计为大型表单应用提供了良好的可维护性和扩展性基础，值得在用户项目中借鉴和应用。

7.9 KiB Raw Blame History