项目概述

Verba 是一个端到端的 RAG 解决方案，集成了文档导入、语义检索和大语言模型生成功能。用户可以在几步之内完成数据导入和问答配置，无需复杂的代码编写。资料来源：setup.py:8

核心特性

资料来源：README.md:15-25

技术架构

技术栈

Verba 采用前后端分离的架构设计：

资料来源：setup.py:5-6

系统组件

graph TD
    A[用户界面层] --> B[前端 React 应用]
    B --> C[FastAPI 后端服务]
    C --> D[Weaviate 向量数据库]
    C --> E[文档处理器]
    C --> F[LLM 生成器]
    E --> G[多格式 Reader]
    F --> H[多模型 Generator]
    G --> I[csv, xlsx, 音频, PDF...]
    H --> J[OpenAI, Ollama, Novita...]

资料来源：frontend/app/components/Chat/ChatInterface.tsx:1-50

部署方式

Verba 支持多种部署模式，满足不同用户的需求：

部署模式对比

资料来源：frontend/app/components/Login/LoginView.tsx:80-85

安装方式

# 方式一：pip 安装
pip install goldenverba

# 方式二：源码构建
git clone https://github.com/weaviate/Verba
pip install -e .

# 方式三：Docker 部署
git clone https://github.com/weaviate/Verba
docker compose --env-file <your-env-file> up -d --build

资料来源：README.md:15-35

功能模块

文档管理

Verba 提供完整的文档导入和管理功能：

• 导入方式：支持单个文件、文件夹批量导入、URL 链接导入
• 文件格式：CSV、Excel（xlsx/xls）、PDF、音频文件、文本文件
• 标签系统：用户可为文档添加标签进行分类和过滤
• 来源链接：可添加原始文档的来源链接，方便溯源
• 覆盖选项：支持覆盖同名已存在的文档

资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx:1-80

聊天问答

用户可以通过聊天界面与数据交互：

graph LR
    A[用户提问] --> B[语义检索]
    B --> C[相关文档块]
    C --> D[LLM 生成]
    D --> E[返回答案]
    C --> F[展示引用来源]

• 语义检索：基于向量相似度匹配相关文档块
• 上下文展示：显示检索到的文档片段及其来源
• 配置选项：可调整 RAG 管道的各项参数

资料来源：frontend/app/components/Chat/ChatInterface.tsx:80-120

系统设置

Settings 页面提供系统级配置功能：

资料来源：frontend/app/components/Settings/InfoView.tsx:30-60

导航结构

前端应用包含以下主要页面：

资料来源：frontend/app/components/Navigation/NavbarComponent.tsx:30-60

版本历史

Verba 采用语义化版本号，当前版本为 2.1.3。主要版本更新如下：

资料来源：CHANGELOG.md:1-30

环境配置

Verba 支持通过环境变量配置 API 密钥和部署选项：

主要环境变量

资料来源：README.md:40-60

快速入门

步骤一：选择部署方式

首次启动时，用户需要选择连接方式：

1. Weaviate - 连接 Weaviate Cloud Service
2. Docker - 使用 Docker 部署的本地实例
3. Custom - 自定义 Weaviate URL 和端口
4. Local - 使用本地完整部署

资料来源：frontend/app/components/Login/LoginView.tsx:80-120

步骤二：导入数据

进入"Import Data"页面后，用户可以：

• 选择"Add Files"添加单个或多个文件
• 选择"Add Directory"批量导入文件夹
• 选择"Add URL"通过链接导入

导入后可在"Overview"或"Configure"标签页中单独配置每个文件。资料来源：README.md:65-70

步骤三：开始问答

数据导入完成后，切换到"Chat"页面即可开始提问。系统会根据检索到的相关文档块生成回答，用户可以查看答案的引用来源。资料来源：README.md:72-75

项目结构

Verba/
├── frontend/                    # React 前端应用
│   └── app/
│       ├── components/          # React 组件
│       │   ├── Chat/            # 聊天相关组件
│       │   ├── Ingestion/       # 数据导入组件
│       │   ├── Login/           # 登录相关组件
│       │   ├── Navigation/      # 导航组件
│       │   └── Settings/        # 设置组件
│       └── page.tsx             # 主页面
├── goldenverba/                 # Python 后端包
│   └── server/                  # 后端服务代码
├── README.md                    # 项目说明
├── CHANGELOG.md                 # 变更日志
├── setup.py                     # 包配置
└── docker-compose.yml           # Docker 编排文件

下一步

• 阅读完整的 技术文档 了解架构细节
• 查看 贡献指南 参与项目开发
• 访问 GitHub 仓库 获取最新更新

系统架构概述

Verba 采用前后端分离的微服务架构，前端使用 React/Next.js 构建响应式界面，后端基于 FastAPI 提供 API 服务。系统支持多种部署模式，以适应不同的使用场景。

graph TD
    A[用户界面层] --> B[前端 React 应用]
    B --> C[WebSocket / REST API]
    C --> D[FastAPI 后端服务]
    D --> E[Weaviate 向量数据库]
    D --> F[LLM 生成器]
    D --> G[嵌入模型]
    E --> H[数据存储层]
    F --> I[外部 LLM API]
    G --> J[嵌入服务]

部署模式

Verba 提供四种部署模式，满足从本地开发到云端生产环境的不同需求。

资料来源：README.md:40-44

部署模式选择界面

在 LoginView.tsx 组件中实现了部署模式选择逻辑，用户可以通过界面选择所需的部署方式。

// frontend/app/components/Login/LoginView.tsx
{production == "Local" && (
  <VerbaButton
    title="Weaviate"
    Icon={FaDatabase}
    onClick={() => setSelectedDeployment("Weaviate")}
  />
)}

文档导入与处理

Verba 提供灵活的文档导入功能，支持多种数据格式和来源。

支持的文件格式

在 2.1.3 版本中，DefaultReader 扩展了以下文件格式支持：

资料来源：CHANGELOG.md:8-10

文档导入流程

graph LR
    A[选择数据源] --> B[添加文件/目录/URL]
    B --> C{数据源类型}
    C -->|文件| D[文件读取器]
    C -->|目录| E[批量文件处理]
    C -->|URL| F[网页抓取器]
    D --> G[文档解析]
    E --> G
    F --> G
    G --> H[文档对象创建]
    H --> I[配置处理管道]
    I --> J[存储至 Weaviate]

导入配置功能

BasicSettingView.tsx 组件提供了文档导入时的基本配置选项：

• 来源链接（Source Link）：添加文档原始来源的引用链接，用户可通过文档浏览器中的"查看来源"按钮访问
• 标签（Labels）：为文档添加自定义标签，便于分类和检索

// frontend/app/components/Ingestion/BasicSettingView.tsx
<div className="flex gap-2 justify-between items-center text-text-verba">
  <p className="flex min-w-[8vw]">Source Link</p>
  <label className="input flex items-center gap-2 w-full bg-bg-verba">
    <input
      type="text"
      className="grow w-full"
      value={source}
      onChange={handleSourceChange}
      disabled={blocked}
    />
  </label>
</div>

资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx

文档对象模型

Verba 使用统一的 Document 类表示所有文档内容，该类封装了文档的元数据和内容信息。

Document 类结构

# goldenverba/components/document.py
@dataclass
class Document:
    title: str              # 文档标题
    content: str            # 文档正文内容
    extension: str          # 文件扩展名
    doc_id: str = ""        # 文档唯一标识
    content_id: str = ""   # 内容块唯一标识
    labels: List[str] = field(default_factory=list)  # 标签列表
    source: str = ""        # 来源链接
    fileSize: int = 0      # 文件大小
    metadata: str = ""     # 元数据字符串
    meta: dict = field(default_factory=dict)  # 元数据字典

资料来源：goldenverba/components/document.py

创建文档工厂函数

def create_document(content: str, fileConfig: FileConfig) -> Document:
    """从文件内容创建 Document 对象"""
    return Document(
        title=fileConfig.filename,
        content=content,
        extension=fileConfig.extension,
        labels=fileConfig.labels,
        source=fileConfig.source,
        fileSize=fileConfig.file_size,
        metadata=fileConfig.metadata,
        meta={},
    )

RAG 处理管道

Verba 实现了完整的 RAG（检索增强生成）处理管道，包括读取器、分块器、嵌入器和生成器四个核心组件。

组件架构

graph TD
    subgraph RAG管道
        A[Reader 读取器] --> B[Chunking 分块器]
        B --> C[Embedding 嵌入器]
        C --> D[Vector Store 向量存储]
        D --> E[Retrieval 检索]
        E --> F[Generator 生成器]
        F --> G[Response 响应]
    end

HTML 读取器实现

HTMLReader.py 提供了网页内容抓取和转换功能，支持以下配置选项：

# goldenverba/components/reader/HTMLReader.py
async def load(self, config: dict, fileConfig: FileConfig) -> list[Document]:
    reader = BasicReader()
    urls = config["URLs"].values
    to_markdown = config["Convert To Markdown"].value
    recursive = config["Recursive"].value
    max_depth = int(config["Max Depth"].value)
    
    documents = []
    processed_urls = set()
    
    async with aiohttp.ClientSession() as session:
        for url in urls:
            await self.process_url(...)

资料来源：goldenverba/components/reader/HTMLReader.py

聊天问答界面

Verba 的聊天界面允许用户使用自然语言查询已导入的文档，系统会返回语义相关的文档片段并生成答案。

聊天流程

sequenceDiagram
    participant U as 用户
    participant C as 前端界面
    participant S as 后端服务
    participant W as Weaviate
    participant L as LLM
    
    U->>C: 输入问题
    C->>S: 发送查询请求
    S->>W: 语义检索相关片段
    W-->>S: 返回 Top-K 相关片段
    S->>L: 发送上下文+问题
    L-->>S: 生成回答
    S-->>C: 返回答案+引用片段
    C->>U: 显示结果

界面组件结构

ChatInterface.tsx 实现了完整的聊天交互界面，包含以下功能区域：

• 消息显示区：展示用户问题和系统回答
• 配置面板：调整 RAG 管道参数
• 输入区域：文本输入框用于提交问题
• 状态指示器：显示检索（Retrieving）和生成（Generating）状态

// frontend/app/components/Chat/ChatInterface.tsx
<span className="text-text-alt-verba loading loading-dots loading-md"></span>
<p className="text-text-alt-verba">
  {fetchingStatus === "CHUNKS" && "Retrieving..."}
  {fetchingStatus === "RESPONSE" && "Generating..."}
</p>

资料来源：frontend/app/components/Chat/ChatInterface.tsx

取消操作

用户可以随时取消正在进行的检索或生成操作：

<button
  onClick={() => {
    setFetchingStatus("DONE");
    isFetching.current = false;
  }}
  className="btn btn-circle btn-sm bg-bg-alt-verba hover:bg-warning-verba"
>
  <MdCancel size={15} />
</button>

生成器与嵌入器

Verba 支持多种 LLM 提供商和嵌入模型，用户可根据需求灵活配置。

支持的 LLM 提供商

资料来源：CHANGELOG.md:4-24

环境变量配置

Verba 支持通过环境变量配置模型：

系统设置与管理

InfoView 设置面板

InfoView.tsx 组件提供了全面的系统管理功能：

graph TD
    A[设置面板] --> B[集群信息]
    A --> C[集合管理]
    A --> D[重置操作]
    
    B --> B1[节点状态]
    B --> B2[分片信息]
    
    C --> C1[集合列表]
    C --> C2[对象计数]
    
    D --> D1[重置文档]
    D --> D2[重置配置]
    D --> D3[重置建议]
    D --> D4[重置全部]

重置操作

// frontend/app/components/Settings/InfoView.tsx
<UserModalComponent
  modal_id="reset-documents"
  title="Reset Documents"
  text="Are you sure you want to reset all documents? This will clear all documents and chunks from Verba."
  triggerAccept={resetDocuments}
  triggerString="Reset"
/>

导航与界面布局

顶部导航栏

NavbarComponent.tsx 实现了应用的主要导航结构：

graph LR
    A[导航栏] --> B[Chat 聊天]
    A --> C[Documents 文档]
    A --> D[Import Data 导入数据]
    A --> E[Settings 设置]
    
    style A fill:#e1f5fe
    style B fill:#b3e5fc
    style C fill:#b3e5fc
    style D fill:#b3e5fc
    style E fill:#b3e5fc

导航按钮组件

// frontend/app/components/Navigation/NavbarComponent.tsx
<NavbarButton
  hide={false}
  Icon={IoChatbubbleSharp}
  title="Chat"
  currentPage={currentPage}
  setCurrentPage={setCurrentPage}
  setPage="CHAT"
/>
{production != "Demo" && (
  <NavbarButton
    hide={false}
    Icon={IoMdAddCircle}
    title="Import Data"
    currentPage={currentPage}
    setCurrentPage={setCurrentPage}
    setPage="ADD"
  />
)}

资料来源：frontend/app/components/Navigation/NavbarComponent.tsx

文档浏览器

ContentView 文档内容展示

ContentView.tsx 组件提供了文档内容的分页浏览功能：

• 分块导航：支持按块（Chunk）或按页（Page）浏览
• 内容渲染：将文档内容片段渲染为可读文本
• 标签显示：展示文档关联的标签

// frontend/app/components/Document/ContentView.tsx
<div className="flex justify-center items-center gap-2 p-3 bg-bg-alt-verba">
  <VerbaButton
    title={"Previous " + (chunkScores ? "Chunk" : "Page")}
    onClick={previousPage}
    className="btn-sm min-w-min max-w-[200px]"
  />
  <div className="flex items-center">
    <p className="text-xs text-text-verba">
      {chunkScores ? "Chunk " : "Page "} {page}
    </p>
  </div>
  <VerbaButton
    title={"Next " + (chunkScores ? "Chunk" : "Page")}
    onClick={nextPage}
  />
</div>

快速入门

安装方式

Verba 提供三种安装方式：

# pip 安装
pip install goldenverba

# 源码构建
git clone https://github.com/weaviate/Verba
pip install -e .

# Docker 部署
git clone https://github.com/weaviate/Verba
docker compose --env-file <your-env-file> up -d --build

环境变量配置

在项目根目录创建 .env 文件配置 API 密钥和环境变量。Verba 会自动读取该文件中的配置。

注意：仅设置需要使用的环境变量，缺失或错误的值可能导致运行错误。

资料来源：README.md:58-75

版本历史

资料来源：CHANGELOG.md

概述

Verba（Golden RAGtriever）是一个开源的检索增强生成（RAG）应用程序，旨在为用户提供一个简化、易用的 RAG 解决方案。该项目由 Weaviate 团队开发维护，支持多种部署方式和 LLM 提供商集成。资料来源：README.md

技术栈概览

Verba 采用前后端分离的架构设计，主要由以下技术组件构成：

资料来源：setup.py

系统架构图

graph TD
    subgraph 前端层["前端层 (Next.js)"]
        A[用户界面] --> B[页面路由]
        B --> C[组件库]
        C --> D[状态管理]
    end
    
    subgraph 后端层["后端层 (FastAPI)"]
        E[API 路由] --> F[Verba Manager]
        F --> G[组件系统]
        G --> H[Weaviate 客户端]
    end
    
    subgraph 数据层["数据层 (Weaviate)"]
        I[向量存储] --> J[集合与对象]
    end
    
    K[文档导入] --> E
    L[聊天查询] --> E
    E --> H
    H --> I
    
    M[LLM 提供商] --> G
    N[嵌入模型] --> G

核心组件架构

前端组件结构

前端采用 Next.js 框架构建，主要包含以下核心组件模块：

资料来源：frontend/app/components/Navigation/NavbarComponent.tsx

后端核心模块

#### Verba Manager

Verba Manager 是系统的核心管理单元，负责协调各个组件之间的交互。该模块处理文档管理、RAG 配置、用户凭证等核心业务逻辑。

# 核心管理功能
- 文档生命周期管理
- RAG 管道配置
- 凭证验证与存储
- 部署环境适配

资料来源：goldenverba/verba_manager.py

#### 组件接口系统

Verba 采用基于接口的组件化设计，所有核心功能都通过标准化接口实现：

graph LR
    A[Reader 接口] --> B[文档读取]
    C[Embedder 接口] --> D[向量嵌入]
    E[Generator 接口] --> F[文本生成]
    G[Chunker 接口] --> H[文档分块]

资料来源：goldenverba/components/interfaces.py

文档对象模型

classDiagram
    class Document {
        +str title
        +str content
        +str extension
        +str fileSize
        +list labels
        +str source
        +dict meta
        +str metadata
    }
    
    class FileConfig {
        +str filename
        +str extension
        +str content
        +str source
        +list labels
        +str file_size
        +dict metadata
    }
    
    Document --> FileConfig : create from

资料来源：goldenverba/components/document.py

部署架构

Verba 支持多种部署模式，以适应不同的使用场景：

graph TD
    A[启动 Verba] --> B{部署模式选择}
    
    B --> C[Local 模式]
    B --> D[Docker 模式]
    B --> E[Weaviate 云服务]
    B --> F[Custom 自定义]
    
    C --> G[本地 Ollama]
    C --> H[本地 HuggingFace]
    
    D --> I[Docker Compose]
    
    E --> J[WCS 云端]
    
    F --> K[自定义 Weaviate 实例]
    K --> L[自定义 API 端点]

资料来源：frontend/app/components/Login/LoginView.tsx

部署模式对比

RAG 处理流程

graph LR
    A[数据导入] --> B[文档读取 Reader]
    B --> C[分块处理 Chunker]
    C --> D[向量化 Embedder]
    D --> E[Weaviate 存储]
    
    F[用户查询] --> G[向量化查询]
    G --> H[向量检索]
    H --> I[上下文组装]
    I --> J[LLM 生成]
    J --> K[返回结果]

聊天界面交互

聊天模块负责用户与 RAG 系统之间的交互：

stateDiagram-v2
    [*] --> 空闲状态: 页面加载
    空闲状态 --> 检索中: 用户发送消息
    检索中 --> 生成中: 获取到上下文
    生成中 --> 空闲状态: 生成完成
    检索中 --> 空闲状态: 取消操作
    生成中 --> 空闲状态: 取消操作

资料来源：frontend/app/components/Chat/ChatInterface.tsx

前端页面结构

graph TD
    A[主页面] --> B[导航栏]
    A --> C[内容区域]
    A --> D[页脚]
    
    B --> B1[Chat 聊天]
    B --> B2[Documents 文档]
    B --> B3[Import Data 导入]
    B --> B4[Settings 设置]
    
    C --> C1{生产模式判断}
    C1 -->|非 Demo| B3
    C1 -->|Demo| 隐藏导入

资料来源：frontend/app/page.tsx

API 服务架构

FastAPI 后端提供以下核心服务接口：

资料来源：goldenverba/server/api.py

初始化流程

sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant B as 后端 API
    participant W as Weaviate
    
    U->>F: 访问应用
    F->>B: 健康检查
    B->>W: 连接验证
    W-->>B: 连接状态
    B-->>F: 部署配置
    F->>U: 显示登录界面
    
    U->>F: 选择部署模式
    F->>B: 验证凭证
    B->>W: 初始化集合
    W-->>B: 初始化完成
    B-->>F: 登录成功
    F->>U: 进入主界面

环境配置

系统通过环境变量进行配置管理：

资料来源：CHANGELOG.md

依赖关系

graph TD
    A[goldenverba] --> B[weaviate-client]
    A --> C[fastapi]
    A --> D[uvicorn]
    A --> E[click]
    
    F[前端] --> G[Next.js]
    F --> H[React]
    F --> I[daisyUI]

核心依赖版本：

• Python: 3.10.0 - 3.12.0
• weaviate-client: 4.9.6
• fastapi: 0.111.1
• uvicorn: 0.29.0

资料来源：setup.py

总结

Verba 采用现代化的前后端分离架构，通过组件化设计实现了高度的灵活性和可扩展性。系统支持多种部署模式，能够适应从本地开发到云端生产的各种使用场景。RAG 管道的模块化设计使得用户可以方便地切换不同的 LLM 提供商和嵌入模型，同时保持核心功能的稳定性和一致性。

概述

Verba 前端是基于 Next.js 构建的 React 应用，采用组件化架构设计。该应用作为 RAG（检索增强生成）系统的用户界面，提供聊天交互、文档管理、数据导入和系统设置等功能。前端使用 TypeScript 开发，通过 WebSocket 与后端服务通信，并使用 Tailwind CSS 和 daisyUI 进行样式管理。资料来源：setup.py:1-12

技术栈

组件架构

组件目录结构

Verba 前端组件采用功能模块化组织，所有组件位于 frontend/app/components/ 目录下，按功能分为以下子目录：

frontend/app/components/
├── Chat/           # 聊天相关组件
├── Document/       # 文档浏览组件
├── Ingestion/      # 数据导入组件
├── Login/          # 登录与初始化组件
├── Navigation/     # 导航组件
└── Settings/       # 设置组件

资料来源：frontend/app/components/Chat/ChatMessage.tsx, frontend/app/components/Navigation/NavbarComponent.tsx

核心组件关系

graph TD
    A[主页面 page.tsx] --> B[NavbarComponent 导航栏]
    A --> C[主内容区域]
    
    C --> D{currentPage 状态}
    D -->|CHAT| E[ChatInterface 聊天界面]
    D -->|DOCUMENTS| F[DocumentView 文档视图]
    D -->|ADD| G[IngestionView 导入视图]
    D -->|SETTINGS| H[InfoView 设置视图]
    D -->|LOGIN| I[LoginView 登录视图]
    
    E --> J[ChatMessage 消息组件]
    E --> K[ChatConfig 聊天配置]
    
    G --> L[FileSelectionView 文件选择]
    G --> M[BasicSettingView 基础设置]
    
    B --> N[StatusMessenger 状态消息]

导航系统

导航栏组件

NavbarComponent 是应用的主导航组件，负责页面路由切换和状态显示。该组件根据 production 环境变量决定是否显示特定功能按钮。

资料来源：frontend/app/components/Navigation/NavbarComponent.tsx:1-150

导航按钮配置表：

导航栏支持响应式设计，在移动端（md 断点以下）以汉堡菜单形式展示，在桌面端以横向按钮组形式展示。组件使用 useState 管理当前页面状态，通过 setCurrentPage 回调向上层组件传递页面变更。资料来源：frontend/app/components/Navigation/NavbarComponent.tsx:50-100

状态消息组件

StatusMessengerComponent 提供全局状态通知功能，通过 AnimatePresence 实现动画效果。消息根据类型（info、success、error）显示不同颜色，消息有效期为 5 秒。资料来源：frontend/app/components/Navigation/StatusMessenger.tsx:1-40

sequenceDiagram
    participant Parent as 父组件
    participant StatusMessenger
    participant Message as 消息队列
    
    Parent->>StatusMessenger: addStatusMessage(type, message)
    StatusMessenger->>Message: 添加消息到队列
    Note over Message: 设置 timestamp
    StatusMessenger->>StatusMessenger: 过滤 5 秒内的消息
    StatusMessenger->>StatusMessenger: 动画显示消息
    Note over StatusMessenger: 5 秒后自动移除

聊天模块

聊天界面组件

ChatInterface 是聊天功能的核心组件，管理消息列表、输入框和状态显示。组件支持以下消息类型：

• user：用户发送的消息，右对齐显示
• system：系统响应，左对齐显示，支持 Markdown 渲染
• error：错误提示，使用警告色背景
• retrieval：检索状态信息

资料来源：frontend/app/components/Chat/ChatInterface.tsx:1-200

消息状态与样式映射表：

聊天界面包含实时检索状态指示器，显示 "Retrieving..." 或 "Generating..." 状态，用户可通过取消按钮终止请求。组件使用 useRef 管理 isFetching 状态以避免闭包问题。资料来源：frontend/app/components/Chat/ChatInterface.tsx:80-120

聊天消息组件

ChatMessage 负责渲染单条聊天消息，支持富文本内容展示。对于 system 类型消息，组件使用 ReactMarkdown 和 SyntaxHighlighter 进行 Markdown 解析和代码语法高亮。资料来源：frontend/app/components/Chat/ChatMessage.tsx:1-100

代码高亮支持根据主题（dark/light）切换样式：

• 暗色主题：使用 oneDark 配色
• 亮色主题：使用 oneLight 配色

组件还支持 cached 属性，当消息为缓存内容时显示数据库图标。资料来源：frontend/app/components/Chat/ChatMessage.tsx:30-60

文档管理模块

文档内容视图

ContentView 组件提供文档和 Chunk 的分页浏览功能。组件支持两种内容模式：

1. Chunk 模式：显示检索到的文档片段，配合相关性分数
2. Page 模式：显示原始文档分页

资料来源：frontend/app/components/Document/ContentView.tsx:1-150

内容显示特征表：

组件使用 Previous/Next 按钮进行分页导航，分页逻辑根据当前模式（Chunk 或 Page）显示不同的按钮文本。资料来源：frontend/app/components/Document/ContentView.tsx:100-130

数据导入模块

文件选择视图

FileSelectionView 组件管理导入文件的列表展示和选择状态。组件支持多种 Reader 类型筛选，包括 URL 类型 Reader 的下拉菜单选择。资料来源：frontend/app/components/Ingestion/FileSelectionView.tsx:1-100

文件组件交互流程：

graph LR
    A[FileSelectionView] --> B[FileComponent 列表]
    B --> C{用户操作}
    C -->|选择| D[setSelectedFileData]
    C -->|删除| E[handleDeleteFile]
    C -->|添加URL| F[handleAddURL]
    
    G[导入就绪] --> H[Import Selected 按钮]
    H --> I[触发导入流程]

文件列表区域使用 overflow-auto 支持滚动，导入操作仅在 WebSocket 在线时可用。资料来源：frontend/app/components/Ingestion/FileSelectionView.tsx:80-120

基础设置视图

BasicSettingView 组件提供导入文件的详细配置选项，包括 RAG Pipeline 各组件的配置。资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx:1-150

配置项表：

组件使用 onKeyDown 事件监听 Enter 键快速添加标签，文本域最大高度限制为 150px。资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx:50-100

设置模块

信息视图

InfoView 组件显示系统状态信息和提供重置功能入口。组件从后端 API 获取集群节点信息和 Collection 列表。资料来源：frontend/app/components/Settings/InfoView.tsx:1-100

信息展示区域表：

InfoView 提供四种重置操作，分别通过 UserModalComponent 组件确认后执行：

1. Reset Documents：清除所有文档和分块
2. Reset Config：重置配置
3. Reset Verba：删除 Verba 相关 Collection
4. Reset Suggestions：清除自动完成建议

资料来源：frontend/app/components/Settings/InfoView.tsx:90-120

登录与初始化

登录视图

LoginView 组件处理应用初始化和部署类型选择。根据 production 环境变量显示不同界面：资料来源：frontend/app/components/Login/LoginView.tsx:1-80

部署类型选择表：

组件使用 isConnecting 状态管理连接中动画，通过 setSelectedDeployment 回调传递选择结果。资料来源：frontend/app/components/Login/LoginView.tsx:50-70

入门引导

GettingStartedComponent 组件在首次使用时显示引导界面，包含项目介绍和缩略图展示。用户点击 "Let's get started" 按钮后通过 localStorage 记录已显示状态。资料来源：frontend/app/components/Login/GettingStarted.tsx:1-60

主页面结构

page.tsx 作为应用的根组件，组合所有子组件并管理全局状态。主要功能包括：资料来源：frontend/app/page.tsx:1-100

1. 生产环境检测：根据 NEXT_PUBLIC_VERBA_PRODUCTION 环境变量决定显示模式
2. 组件挂载：在生产环境下挂载 Navbar 和主内容区域
3. 底部信息：显示构建信息和版权声明
4. 追踪像素：集成 Scarf 分析工具

graph TD
    A[page.tsx] --> B{production 环境}
    B -->|Demo| C[隐藏导航栏]
    B -->|非 Demo| D[显示 NavbarComponent]
    D --> E[显示主内容区域]
    E --> F[Footer + 追踪像素]
    
    G[GettingStarted 检测] --> H{localStorage}
    H -->|首次| I[显示引导弹窗]
    H -->|非首次| J[跳过]

数据流与状态管理

组件间通信模式

Verba 前端采用以下状态管理模式：

API 通信

前端通过 frontend/app/api.ts 定义的 API 函数与后端通信，包括：

• 认证与部署配置
• 文档操作（CRUD）
• RAG 配置获取与更新
• 系统状态查询

WebSocket 连接用于实时聊天消息传输和导入进度更新。

样式系统

Verba 主题变量

应用定义了统一的颜色变量系统，以 -verba 后缀区分：

资料来源：frontend/app/components/Chat/ChatMessage.tsx:20-30, frontend/app/components/Settings/InfoView.tsx:1-50

响应式设计

应用采用移动优先的响应式设计策略：

总结

Verba 前端采用组件化、模块化的架构设计，通过清晰的功能划分实现聊天、文档管理、数据导入和系统设置等核心功能。组件间通过 props、回调函数和 React Hooks 进行状态管理，样式系统基于 Tailwind CSS 和 daisyUI 提供一致的用户体验。

系统架构概述

Verba 的后端组件系统基于 Python 实现，采用面向接口的编程范式。核心组件类型包括：

该系统通过 goldenverba/components/ 目录下的模块进行组织，所有组件均实现统一的接口规范，从而保证系统的可扩展性和可维护性。资料来源：setup.py:1-15

核心类型定义

Document 数据模型

Document 是系统中最核心的数据单元，用于表示待处理的文档或文本内容：

Document(
    title=str,           # 文档标题
    content=str,         # 文档内容
    extension=str,       # 文件扩展名
    labels=list,         # 标签列表
    source=str,          # 原始来源链接
    fileSize=str,        # 文件大小
    metadata=dict,       # 元数据
    meta=dict            # 配置元数据
)

文档创建可通过 create_document() 函数完成，该函数接收文件内容 content 和 FileConfig 配置对象，返回完整的 Document 实例。资料来源：goldenverba/components/document.py:40-49

FileConfig 配置模型

FileConfig 用于配置单个文件的导入设置：

FileConfig(
    filename=str,        # 文件名
    extension=str,       # 扩展名
    labels=list,         # 文件标签
    source=str,          # 来源链接
    file_size=str,       # 文件大小
    metadata=str,        # 元数据字符串
)

组件类型枚举

系统定义了标准化的组件类型枚举，用于区分不同功能的组件：

组件接口规范

Verba 采用面向接口的设计原则，所有组件必须实现相应的抽象接口。接口定义确保了组件之间的解耦，使得添加新的提供商实现变得简单高效。

组件生命周期

graph TD
    A[初始化组件] --> B[加载配置]
    B --> C[建立连接]
    C --> D[执行操作]
    D --> E[返回结果]
    E --> F[释放资源]

组件的典型生命周期包括：初始化、配置加载、连接建立、执行具体操作、结果返回和资源释放。每一步都遵循统一的错误处理机制。

环境变量配置

Verba 支持通过环境变量配置组件行为，以下是主要配置项：

这些环境变量允许用户在启动前预先配置组件，减少前端交互中的配置负担。资料来源：CHANGELOG.md:8-12

支持的组件提供商

已集成的生成器

已集成的嵌入器

系统支持多种嵌入模型集成，包括本地 Ollama 模型和云服务提供商的模型。通过统一接口封装，切换不同的嵌入提供商只需修改配置而无需更改业务代码。

已集成的读取器

版本 2.1.3 新增了对 CSV、Excel 格式的原生支持，扩展了文档处理的覆盖范围。资料来源：CHANGELOG.md:12

组件管理器

组件管理器（Managers）负责组件的注册、发现和生命周期管理。它维护了系统中所有可用组件的目录，并提供组件实例化、配置更新和状态监控的功能。

graph LR
    A[前端请求] --> B[Verba Manager]
    B --> C[组件选择]
    C --> D[配置应用]
    D --> E[组件执行]
    E --> F[结果返回]

管理器核心职责

• 组件注册：将新组件注册到系统中
• 配置管理：维护各组件的配置状态
• 依赖解析：处理组件间的依赖关系
• 资源分配：管理组件使用的计算资源

部署模式与组件关系

Verba 支持四种部署模式，不同模式下启用的组件有所不同：

在 Demo 模式下，部分管理功能（如 Import Data、Settings）会被隐藏，仅保留核心的 Chat 功能。资料来源：NavbarComponent.tsx:15-30

前端配置交互

前端通过标准化接口与后端组件系统交互，主要涉及以下配置文件：

interface RAGConfig {
    "Reader": { components: Record<string, ComponentConfig> };
    "Embedder": { components: Record<string, ComponentConfig> };
    "Generator": { components: Record<string, ComponentConfig> };
    "Retriever": { components: Record<string, ComponentConfig> };
}

前端组件如 ChatConfig.tsx 负责渲染各组件的配置界面，用户可以动态选择和配置 Reader、Embedder、Generator 和 Retriever。资料来源：ChatConfig.tsx:20-40

版本演进

组件系统的持续演进体现了 Verba 对多提供商支持和格式兼容性的重视。

开发指南

添加新组件

1. 在 goldenverba/components/ 下创建新的组件文件
2. 实现统一的组件接口
3. 在组件管理器中注册新组件
4. 在前端添加对应的配置界面

配置验证

系统启动时会验证环境变量和 API Key 的有效性。建议使用 .env 文件集中管理敏感配置，Verba 会自动读取并应用这些配置。

概述

Verba 的数据导入与处理模块是 RAG（检索增强生成）流水线的核心入口，负责将各类数据源（文件、目录、URL）摄入系统并进行预处理。该模块支持多种文件格式的读取、文档分块（Chunking）、向量化（Embedding）等关键步骤，最终将处理后的数据存储至 Weaviate 向量数据库中。

从 CHANGELOG.md 的记录可知，Verba 2.1.3 版本已添加对 csv、xlsx、xls 格式的支持，显著扩展了数据导入的灵活性。资料来源：CHANGELOG.md:10-12

核心架构

Verba 的数据处理采用模块化 RAG 配置架构，每个文档可独立配置 Reader、Chunker、Embedder 组件。这种设计允许用户根据不同数据类型选择最优的处理策略。

graph TD
    A[用户导入数据] --> B[Reader 组件]
    B --> C[Chunker 分块]
    C --> D[Embedder 向量化]
    D --> E[Weaviate 存储]
    
    F[文件/目录/URL] --> B
    G[元数据配置] --> E
    H[标签管理] --> E

数据导入流程

导入方式

Verba 前端界面提供了三种数据导入方式，分别对应不同的使用场景：

资料来源：README.md:28-32

导入界面组件

前端 NavbarComponent.tsx 中的导航栏提供了 "Import Data" 入口，该入口仅在非 Demo 模式下显示：

{production != "Demo" && (
  <NavbarButton
    hide={false}
    Icon={IoMdAddCircle}
    title="Import Data"
    currentPage={currentPage}
    setCurrentPage={setCurrentPage}
    setPage="ADD"
  />
)}

资料来源：frontend/app/components/Navigation/NavbarComponent.tsx:45-54

文件配置选项

在 BasicSettingView.tsx 中，Verba 提供了丰富的文件配置选项，每个文件可独立设置以下参数：

基本信息配置

资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx:28-70

标签管理

用户可以通过输入框添加标签，按 Enter 键或点击 Add 按钮即可添加标签到当前文档：

<input
  type="text"
  value={label}
  onChange={(e) => setLabel(e.target.value)}
  onKeyDown={(e) => {
    if (e.key === "Enter") {
      e.preventDefault();
      addLabel(label);
    }
  }}
/>

资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx:36-48

元数据配置

元数据以 JSON 格式存储，会被添加到发送给 Embedder 和 Generator 的上下文中，从而影响检索和生成结果：

<textarea
  className="grow w-full textarea flex items-center gap-2 max-h-64 bg-bg-verba"
  value={metadata}
  onChange={handleMetadataChange}
/>

资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx:93-98

RAG 组件配置

每个导入的文件都可以独立配置其 RAG 流水线中的关键组件：

Chunker 分块器

用于将长文档切分为适合检索的较小单元。分块策略直接影响后续检索的质量和上下文完整性。

Embedder 向量化器

负责将文本内容转换为向量表示，存储至 Weaviate 以支持语义检索。

<div className="flex gap-2 justify-between items-center text-text-verba">
  <p className="flex min-w-[8vw]">Embedder</p>
  <label className="input flex items-center gap-2 w-full bg-bg-verba">
    <input
      type="text"
      className="grow w-full"
      value={fileMap[selectedFileData].rag_config["Embedder"].selected}
      disabled={true}
    />
  </label>
</div>

资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx:148-160

文档对象模型

Document 类是 Verba 中数据表示的核心结构，定义在 goldenverba/components/document.py 中：

def create_document(content: str, fileConfig: FileConfig) -> Document:
    """Create a Document object from the file content."""
    return Document(
        title=fileConfig.filename,
        content=content,
        extension=fileConfig.extension,
        labels=fileConfig.labels,
        source=fileConfig.source,
        fileSize=fileConfig.file_size,
        metadata=fileConfig.metadata,
        meta={},
    )

资料来源：goldenverba/components/document.py:56-68

Document 对象包含以下核心字段：

分块查看器

导入后的文档可以通过 Document Explorer 查看其分块内容。ChunkView.tsx 组件负责渲染和导航分块：

<div className="flex gap-2 items-center p-3 bg-secondary-verba rounded-full w-fit">
  <IoNewspaper size={12} />
  <p className="text-xs flex text-text-verba">
    Chunk {chunks[currentChunkIndex].chunk_id}
  </p>
</div>

资料来源：frontend/app/components/Document/ChunkView.tsx:28-34

分块导航

支持 Previous 和 Next 按钮进行分块间的导航切换：

<VerbaButton
  title={"Previous " + (chunkScores ? "Chunk" : "Page")}
  onClick={previousPage}
/>
<VerbaButton
  title={"Next " + (chunkScores ? "Chunk" : "Page")}
  onClick={nextPage}
/>

资料来源：frontend/app/components/Document/ContentView.tsx:52-68

文件导入流程图

graph LR
    A[选择导入方式] --> B{导入类型}
    B -->|文件| C[上传文件]
    B -->|目录| D[选择目录]
    B -->|URL| E[输入URL]
    
    C --> F[配置Reader组件]
    D --> F
    E --> F
    
    F --> G[配置Chunker]
    G --> H[配置Embedder]
    H --> I[设置元数据]
    
    I --> J[点击Import Selected]
    J --> K[后端处理]
    K --> L[存入Weaviate]
    L --> M[导入完成]

环境变量配置

Verba 支持通过 .env 文件预配置导入相关的环境变量，无需在界面中重复输入：

资料来源：CHANGELOG.md:8-9

依赖项

数据导入模块依赖以下核心 Python 包，定义在 setup.py 中：

资料来源：setup.py:18-23

最佳实践

文件命名

建议为文档设置有意义的标题，便于后续在 Document Explorer 中识别和检索。系统会自动为 URL 类型的内容使用其 URL 作为默认文件名。

元数据使用

合理使用元数据可以显著提升检索精度。元数据会被添加到上下文请求中，影响嵌入和生成结果。建议添加文档来源、时间、作者等关键信息。

标签管理

使用一致的标签体系有助于组织大量文档。标签可用于快速过滤和分组相关文档。

分块策略选择

根据文档类型选择合适的分块策略。长文档建议使用语义分块（Semantic Chunking），短文档可使用固定长度分块。

概述

Verba 是一个开源的 RAG（Retrieval-Augmented Generation，检索增强生成）应用，名为 "Golden RAGtriever"。该项目由 Weaviate 团队开发，旨在为检索增强生成应用提供流线型、用户友好的界面。Verba 允许用户通过几个简单步骤深入数据并进行有意义的交互。

RAG 流程是 Verba 的核心功能，它将文档检索与语言模型生成相结合，使用户能够针对自己的数据提出问题并获得基于上下文的答案。

系统架构

graph TD
    A[用户提问] --> B[Chat Interface]
    B --> C{检索阶段}
    C --> D[Embedder 嵌入向量]
    D --> E[Weaviate 向量数据库]
    E --> F[Retriever 检索相关 Chunk]
    F --> G{生成阶段}
    G --> H[Generator 生成模型]
    H --> I[返回答案与上下文]
    
    J[数据导入] --> K[Reader 读取文件]
    K --> L[Chunker 分块处理]
    L --> M[Embedder 向量化]
    M --> E

核心组件

组件配置架构

Verba 的 RAG 管道由三个核心组件构成，通过 ChatConfig 组件进行统一配置管理：

资料来源：frontend/app/components/Chat/ChatConfig.tsx:33-48

<ComponentView
  RAGConfig={RAGConfig}
  component_name="Embedder"
  selectComponent={selectComponent}
  updateConfig={updateConfig}
  saveComponentConfig={saveComponentConfig}
  blocked={production == "Demo"}
/>
<ComponentView
  RAGConfig={RAGConfig}
  component_name="Generator"
  selectComponent={selectComponent}
  updateConfig={updateConfig}
  saveComponentConfig={saveComponentConfig}
  blocked={production == "Demo"}
/>
<ComponentView
  RAGConfig={RAGConfig}
  component_name="Retriever"
  selectComponent={selectComponent}
  updateConfig={updateConfig}
  saveComponentConfig={saveComponentConfig}
  blocked={production == "Demo"}
/>

检索流程详解

向量化与存储

用户导入的文档经过以下处理流程进入系统：

1. 文档读取：通过 Reader 组件读取多种格式的文件（包括 csv、xlsx、xls 等）
2. 文档创建：使用 Document 类封装文档元数据
3. 分块处理：将文档切分为适合检索的文本块（Chunks）
4. 向量化存储：通过 Embedder 将文本块转换为向量，存储于 Weaviate 向量数据库

资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx:60-70 资料来源：goldenverba/components/document.py:42-53

检索过程

graph LR
    A[用户问题] --> B[Query 向量化]
    B --> C[向量相似度搜索]
    C --> D[Top-K 检索]
    D --> E[返回相关 Chunks]
    E --> F[传递给 Generator]

当用户在 Chat 界面输入问题时，系统执行以下步骤：

1. 问题向量化：用户输入的查询文本通过 Embedder 转换为查询向量
2. 向量搜索：在 Weaviate 中执行向量相似度搜索
3. 结果排序：根据相似度得分返回最相关的 K 个文档块
4. 状态展示：前端显示 "Retrieving..." 状态提示

资料来源：frontend/app/components/Chat/ChatInterface.tsx:8-15

<p className="text-text-alt-verba">
  {fetchingStatus === "CHUNKS" && "Retrieving..."}
  {fetchingStatus === "RESPONSE" && "Generating..."}
</p>

生成流程详解

上下文增强的生成

检索到的文档块（Chunks）与用户问题一起作为上下文传递给 Generator 组件：

graph TD
    A[用户问题] --> E
    B[检索到的 Chunks] --> E
    E[上下文组装] --> F[Prompt 构建]
    F --> G[LLM 生成]
    G --> H[返回答案]

Generator 组件支持多种大语言模型提供者，包括：

• OpenAI（支持动态模型名称获取）
• Ollama（支持 OLLAMA_MODEL 和 OLLAMA_EMBED_MODEL 环境变量配置）
• Novita
• Upstage
• Groq
• Anthropic（通过 Ollama 或 LLM 提供商）

资料来源：CHANGELOG.md:6-15

响应状态管理

生成过程中的状态通过 fetchingStatus 状态机管理：

用户可以通过取消按钮随时终止检索或生成过程：

<button
  onClick={() => {
    setFetchingStatus("DONE");
    isFetching.current = false;
  }}
  className="btn btn-circle btn-sm bg-bg-alt-verba hover:bg-warning-verba..."
>
  <MdCancel size={15} />
</button>

资料来源：frontend/app/components/Chat/ChatInterface.tsx:16-24

数据模型

Document 类结构

class Document:
    def __init__(
        self,
        title: str,           # 文档标题
        content: str,         # 文档内容
        extension: str,       # 文件扩展名
        labels: List[str],    # 标签列表
        source: str,          # 源链接
        fileSize: int,        # 文件大小
        metadata: str,        # 元数据
        meta: Dict,           # 额外元数据
    )

文档对象在导入时通过 create_document 函数创建，该函数将文件内容与 FileConfig 配置结合生成完整的文档对象。

资料来源：goldenverba/components/document.py:1-53

文件配置结构

导入文件时，系统为每个文件维护独立的配置状态：

interface FileData {
  content: string;           // 文件内容
  rag_config: RAGConfig;     // RAG 组件配置
  block: boolean;            // 是否阻塞
  filename: string;         // 文件名/标题
  source: string;           // 源链接
  labels: string[];         // 标签
  metadata: object;         // 元数据
}

每个文件可以独立配置 Reader、Embedder、Generator 等组件，实现灵活的管道定制。

资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx:1-80

部署模式

Verba 支持多种部署方式，RAG 流程的配置也会相应调整：

可通过 DEFAULT_DEPLOYMENT 环境变量设置默认部署类型。

资料来源：frontend/app/components/Login/LoginView.tsx:15-30 资料来源：README.md:1-30

用户交互界面

导航与页面结构

Verba 前端采用单页应用架构，主要导航入口包括：

graph TD
    A[Navbar] --> B[Chat 页面]
    A --> C[Documents 页面]
    A --> D[Import Data 页面]
    A --> E[Settings 页面]
    
    B --> B1[对话输入]
    B --> B2[聊天历史]
    B --> B3[配置面板]
    
    C --> C1[文档列表]
    C --> C2[内容查看器]
    C --> C3[向量可视化]

导航组件根据部署环境动态显示菜单项：

{production != "Demo" && (
  <li key={"Menu Button4"}>
    <a onClick={() => setCurrentPage("ADD")}>Import Data</a>
  </li>
)}

资料来源：frontend/app/components/Navigation/NavbarComponent.tsx:1-50

文档浏览与 Chunk 导航

在 Documents 页面中，用户可以浏览已导入的文档内容，并按 Chunk 分页查看：

<VerbaButton
  title={"Previous " + (chunkScores ? "Chunk" : "Page")}
  onClick={previousPage}
/>
<p className="text-xs text-text-verba">
  {chunkScores ? "Chunk " : "Page "} {page}
</p>
<VerbaButton
  title={"Next " + (chunkScores ? "Chunk" : "Page")}
  onClick={nextPage}
/>

资料来源：frontend/app/components/Document/ContentView.tsx:40-55

核心技术栈

资料来源：setup.py:1-30

配置管理

运行时配置重置

Settings 页面提供多种重置功能，用于管理 RAG 系统状态：

<UserModalComponent
  modal_id="reset-documents"
  title="Reset Documents"
  text="Are you sure you want to reset all documents? This will clear all documents and chunks from Verba."
  triggerAccept={resetDocuments}
  triggerString="Reset"
/>

资料来源：frontend/app/components/Settings/InfoView.tsx:1-50

总结

Verba 的 RAG 检索与生成流程是一个端到端的智能问答系统：

1. 数据导入阶段：文档通过 Reader 读取、Chunker 分块、Embedder 向量化后存入 Weaviate
2. 检索阶段：用户问题通过 Embedder 向量化，在向量数据库中执行相似度搜索返回相关 Chunks
3. 生成阶段：检索结果与问题组装为 Prompt，传递给 Generator（LLM）生成最终答案
4. 展示阶段：答案与相关上下文在 Chat 界面展示，支持用户继续交互

整个流程高度可配置，支持多种部署模式和多种大语言模型提供商，满足不同场景下的 RAG 应用需求。

概述

模型集成是 Verba（Golden RAGtriever）系统的核心功能模块，负责管理和协调 RAG（检索增强生成）管道中的三类关键组件：嵌入模型（Embedder）、生成模型（Generator） 和 检索器（Retriever）。通过标准化的组件接口设计，Verba 支持灵活接入多种大语言模型提供商和嵌入服务，实现端到端的向量检索与生成式问答功能。

资料来源：frontend/app/components/Chat/ChatConfig.tsx:35-45

架构设计

组件层次结构

Verba 的模型集成采用模块化架构，各组件通过统一的配置接口进行管理：

graph TD
    subgraph "RAG 配置层"
        RAGConfig[RAGConfig 配置对象]
    end
    
    subgraph "嵌入层 Embedder"
        OpenAI_Emb[OpenAI Embedder]
        Cohere_Emb[Cohere Embedder]
        Ollama_Emb[Ollama Embedder]
    end
    
    subgraph "生成层 Generator"
        OpenAI_Gen[OpenAI Generator]
        Anthropic_Gen[Anthropic Generator]
        Gemini_Gen[Gemini Generator]
        Groq_Gen[Groq Generator]
        Novita_Gen[Novita Generator]
        Upstage_Gen[Upstage Generator]
    end
    
    subgraph "检索层 Retriever"
        BM25_R[BM25 Retriever]
        Vector_R[Vector Retriever]
        Hybrid_R[Hybrid Retriever]
    end
    
    RAGConfig --> OpenAI_Emb
    RAGConfig --> OpenAI_Gen
    RAGConfig --> BM25_R
    
    style RAGConfig fill:#f9f,stroke:#333,stroke-width:2px

资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx:50-60

集成流程

模型集成的完整工作流程包括配置选择、内容处理、向量嵌入和生成响应四个阶段：

graph LR
    A[用户选择组件配置] --> B[加载嵌入模型]
    B --> C[加载生成模型]
    C --> D[文档分块 Chunker]
    D --> E[向量嵌入 Embedding]
    E --> F[存储至向量数据库]
    F --> G[用户查询]
    G --> H[检索相关块]
    H --> I[上下文组装]
    I --> J[生成响应]

支持的模型提供商

嵌入模型（Embedder）

Verba 支持多种嵌入模型服务，通过 OLLAMA_EMBED_MODEL 等环境变量进行配置。

资料来源：CHANGELOG.md:7-8

生成模型（Generator）

生成器组件支持多种大语言模型提供商，系统会根据 API 凭证动态获取模型名称。

资料来源：CHANGELOG.md:15-16

检索器（Retriever）

检索器负责从向量数据库中获取相关内容，支持多种检索策略。

配置管理

RAGConfig 结构

RAGConfig 是管理所有组件配置的核心对象，采用组件名称作为键值：

interface RAGConfig {
  "Embedder": {
    selected: string;          // 当前选中的嵌入器名称
    components: {
      [key: string]: {
        name: string;
        type: string;
        description: string;
        models?: string[];    // 可用模型列表
      }
    }
  };
  "Generator": {
    selected: string;
    components: {
      [key: string]: {
        name: string;
        type: string;
        description: string;
      }
    }
  };
  "Retriever": {
    selected: string;
    components: {
      [key: string]: {
        name: string;
        type: string;
        description: string;
      }
    }
  };
}

资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx:30-45

环境变量配置

Verba 支持通过环境变量配置模型集成参数：

资料来源：CHANGELOG.md:7-8

前端配置界面

ChatConfig 组件

ChatConfig 组件提供交互式界面，用于配置 RAG 管道中的三类核心组件：

<div className="flex flex-col justify-start gap-3 rounded-2xl w-full p-6">
  <ComponentView
    RAGConfig={RAGConfig}
    component_name="Embedder"
    selectComponent={selectComponent}
    updateConfig={updateConfig}
    saveComponentConfig={saveComponentConfig}
    blocked={production == "Demo"}
  />
  <ComponentView
    RAGConfig={RAGConfig}
    component_name="Generator"
    selectComponent={selectComponent}
    updateConfig={updateConfig}
    saveComponentConfig={saveComponentConfig}
    blocked={production == "Demo"}
  />
  <ComponentView
    RAGConfig={RAGConfig}
    component_name="Retriever"
    selectComponent={selectComponent}
    updateConfig={updateConfig}
    saveComponentConfig={saveComponentConfig}
    blocked={production == "Demo"}
  />
</div>

资料来源：frontend/app/components/Chat/ChatConfig.tsx:35-55

组件选择机制

组件选择通过 selectComponent 函数处理，该函数更新 RAGConfig 中的 selected 字段：

sequenceDiagram
    participant User as 用户
    participant UI as ChatConfig UI
    participant State as 状态管理
    participant Backend as 后端 API
    
    User->>UI: 选择组件下拉菜单
    UI->>State: 调用 selectComponent()
    State->>Backend: 更新 RAGConfig
    Backend-->>State: 返回更新后的配置
    State-->>UI: 刷新组件视图

配置保存与重置

系统提供两种配置操作：

• 保存配置（onSave）：将当前 RAGConfig 持久化至后端
• 重置配置（onReset）：将配置恢复至默认值

<VerbaButton
  title="Save Config"
  onClick={onSave}
  disabled={production == "Demo"}
/>
<VerbaButton
  title="Reset Config"
  onClick={onReset}
  disabled={production == "Demo"}
/>

资料来源：frontend/app/components/Chat/ChatConfig.tsx:20-30

内容处理流程

文档导入配置

在文档导入阶段，用户可配置以下处理组件：

资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx:1-20

嵌入配置界面

嵌入器配置显示当前选中的嵌入器及其描述信息：

<div className="flex gap-2 justify-between items-center text-text-verba">
  <p className="flex min-w-[8vw]">Embedder</p>
  <label className="input flex items-center gap-2 w-full bg-bg-verba">
    <input
      type="text"
      className="grow w-full"
      value={fileMap[selectedFileData].rag_config["Embedder"].selected}
      disabled={true}
    />
  </label>
</div>

资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx:60-72

调试功能

系统提供调试模式，允许用户查看完整的文件配置 JSON：

<div className="flex gap-2 justify-between items-center text-text-verba">
  <p className="flex min-w-[8vw]">Debug</p>
  <VerbaButton
    Icon={CgDebug}
    onClick={openDebugModal}
    className="max-w-min"
  />
</div>

调试输出会过滤掉 content 属性，仅显示配置结构：

const objCopy = { ...fileMap[selectedFileData] };
objCopy.content = "File Content";
return JSON.stringify(objCopy, null, 2);

资料来源：frontend/app/components/Ingestion/BasicSettingView.tsx:95-110

系统信息展示

InfoView 组件

InfoView 组件展示当前集成的系统信息，包括连接状态和版本信息：

<div className="flex flex-col border-2 gap-2 border-bg-verba shadow-sm p-4 rounded-lg">
  <p className="text-sm lg:text-base font-semibold text-text-alt-verba">
    Connected to
  </p>
  <p className="text-text-verba">{credentials.url}</p>
</div>

<div className="flex flex-col border-2 gap-2 border-bg-verba shadow-sm p-4 rounded-lg">
  <p className="text-sm lg:text-base font-semibold text-text-alt-verba">
    Deployment
  </p>
  <p className="text-text-verba">{credentials.deployment}</p>
</div>

资料来源：frontend/app/components/Settings/InfoView.tsx:1-20

版本信息

系统显示 Weaviate 和 Verba 的版本信息，用于诊断集成问题：

{nodePayload ? (
  <p className="text-text-verba">{nodePayload.weaviate_version}</p>
) : (
  <span className="loading loading-spinner loading-sm"></span>
)}

依赖管理

Python 依赖

Verba 后端依赖以下核心包实现模型集成：

资料来源：setup.py:15-25

版本更新记录

资料来源：CHANGELOG.md:1-20

最佳实践

模型选择建议

1. 嵌入模型选择：根据向量数据库和语料特性选择合适的嵌入维度
2. 生成模型选择：考虑延迟、成本和能力平衡
3. 检索器选择：混合检索（Hybrid）通常效果最佳

配置管理

• 使用环境变量管理敏感凭证
• 在非 Demo 模式下保存配置以实现持久化
• 定期检查 CHANGELOG 获取最新支持的功能

部署类型概述

Verba 支持四种主要的部署类型，用户可以在首次启动时通过登录界面进行选择：

资料来源：frontend/app/components/Login/LoginView.tsx:55-58

graph TD
    A[Verba 部署选择] --> B[Local 部署]
    A --> C[Docker 部署]
    A --> D[Weaviate Cloud 部署]
    A --> E[Custom 部署]
    
    B --> B1[Weaviate Embedded]
    C --> C1[独立 Weaviate 容器]
    D --> D1[Weaviate Cloud Services]
    E --> E1[自建 Weaviate 实例]

前置要求

Python 环境要求

Verba 对 Python 版本有明确要求：

资料来源：setup.py:9

环境变量配置

Verba 支持通过 .env 文件自动加载环境变量。建议在项目根目录创建 .env 文件，参考 goldenverba/.env.example 文件进行配置。

资料来源：README.md:28-35

方式一：pip 安装部署

这是最简单快捷的部署方式，适合快速体验 Verba。

安装步骤

# 1. 创建虚拟环境
python3 -m virtualenv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate.bat  # Windows

# 2. 安装 Verba
pip install goldenverba

# 3. 启动应用
verba start

# 4. 访问应用
# 访问 http://localhost:8000

资料来源：README.md:40-55

指定端口和主机

verba start --port 8080 --host 0.0.0.0

包信息

资料来源：setup.py:1-12

方式二：从源码构建

适合需要自定义或参与开发的用户。

安装步骤

# 1. 克隆仓库
git clone https://github.com/weaviate/Verba.git

# 2. 创建并激活虚拟环境
python3 -m virtualenv venv
source venv/bin/activate

# 3. 安装（开发模式）
pip install -e .

# 4. 启动
verba start

# 5. 访问
# 访问 http://localhost:8000

资料来源：README.md:87-105

方式三：Docker 部署

Docker 部署方式提供完整的容器化环境，包含 Verba 前端和 Weaviate 数据库。

架构概览

graph LR
    A[用户浏览器] --> B[Verba Frontend<br/>:8000]
    B --> C[Verba Backend]
    C --> D[Weaviate<br/>:8080]
    E[OLLAMA] --> C

快速启动

# 克隆仓库
git clone https://github.com/weaviate/Verba.git

# 配置环境变量
# 编辑 goldenverba/.env 文件

# 启动容器
docker compose --env-file goldenverba/.env up -d --build

Docker Compose 配置

Verba 的 docker-compose.yml 定义了两个核心服务：

资料来源：docker-compose.yml:1-45

Verba 服务配置详情

verba:
  build:
    context: ./
    dockerfile: Dockerfile
  ports:
    - 8000:8000
  environment:
    - WEAVIATE_URL_VERBA=http://weaviate:8080
    - OPENAI_API_KEY=$OPENAI_API_KEY
    - COHERE_API_KEY=$COHERE_API_KEY
    - OLLAMA_URL=http://host.docker.internal:11434
    - OLLAMA_MODEL=$OLLAMA_MODEL
    - OLLAMA_EMBED_MODEL=$OLLAMA_EMBED_MODEL
  volumes:
    - ./data:/data/
  depends_on:
    weaviate:
      condition: service_healthy
  healthcheck:
    test: wget --no-verbose --tries=3 --spider http://localhost:8000
    interval: 5s
    timeout: 10s
    retries: 5

资料来源：docker-compose.yml:2-28

健康检查配置

资料来源：docker-compose.yml:29-34

访问地址

虚拟环境配置

创建虚拟环境

推荐使用虚拟环境避免包冲突：

# 使用 virtualenv
python3 -m virtualenv venv

# 激活虚拟环境
# Linux/macOS
source venv/bin/activate
# Windows
venv\Scripts\activate.bat

资料来源：PYTHON_TUTORIAL.md:1-25

安装依赖

激活虚拟环境后，使用以下命令安装 Verba：

pip install goldenverba
# 或从源码安装
pip install -e .

退出虚拟环境

deactivate

环境变量配置详解

必需的环境变量

根据不同的功能模块，需要配置相应的 API 密钥：

资料来源：docker-compose.yml:14-20

配置优先级

1. 启动时通过命令行参数传入
2. .env 文件中的环境变量
3. 应用内 UI 配置（首次登录后）

部署方式对比

故障排除

常见问题

验证安装

安装完成后，可以通过以下方式验证：

# 检查 Verba 版本
verba --version

# 访问 Web 界面
# 打开浏览器访问 http://localhost:8000

下一步

部署完成后，建议进行以下操作：

1. 配置 API 密钥：在 .env 文件或应用 UI 中配置所需的 API 密钥
2. 导入数据：通过 "Import Data" 功能导入文档
3. 配置 RAG 管道：在 "Config" 页面配置生成模型和检索策略
4. 开始对话：在 "Chat" 页面开始与数据对话

部署类型概述

Verba 支持四种主要的部署类型，每种类型适用于不同的使用场景：

graph TD
    A[Verba 部署类型] --> B[Local 本地部署]
    A --> C[Docker 容器部署]
    A --> D[Weaviate 云服务]
    A --> E[Custom 自定义部署]
    
    B --> B1[本地 Weaviate 实例]
    C --> C1[Docker Compose 环境]
    D --> D1[Weaviate Cloud Services]
    E --> E1[自选 Weaviate 实例]

部署类型对比

资料来源：frontend/app/components/Login/LoginView.tsx:35-85

环境变量配置

Verba 通过环境变量控制应用的核心行为。以下是支持的环境变量及其功能：

核心环境变量

资料来源：CHANGELOG.md:12-14

依赖包版本配置

Verba 的核心依赖版本在 setup.py 中定义：

资料来源：setup.py:18-35

前端配置系统

配置类型定义

Verba 前端使用 TypeScript 定义了完整的配置类型结构：

interface Credentials {
  url: string;          // Weaviate 实例 URL
  deployment: string;   // 部署类型
  api_key?: string;     // API 密钥（可选）
}

部署模式判断

前端根据 production 环境变量决定显示的界面选项：

graph TD
    A[production 值] --> B["Demo"]
    A --> C["Local"]
    A --> D["Production"]
    
    C --> C1[显示部署选择界面]
    C1 --> C2[Weaviate 选项]
    C1 --> C3[Docker 选项]
    C1 --> C4[Custom 选项]
    C1 --> C5[Local 选项]
    
    B --> B1[显示演示模式入口]
    D --> D1[直接启动 Verba]

资料来源：frontend/app/components/Login/LoginView.tsx:45-90

导航菜单显示逻辑

配置菜单的显示取决于当前部署模式：

资料来源：frontend/app/components/Navigation/NavbarComponent.tsx:15-40

RAG 配置组件

ChatConfig 配置面板

ChatConfig 组件允许用户配置 RAG 管道的各个组件：

graph LR
    A[聊天配置面板] --> B[Reader 读取器]
    A --> C[Embedder 嵌入器]
    A --> D[Generator 生成器]
    A --> E[Chunker 分块器]

配置重置与保存

资料来源：frontend/app/components/Chat/ChatConfig.tsx 资料来源：frontend/app/components/Chat/ChatInterface.tsx:25-45

自定义部署配置

Custom 部署类型允许用户指定完整的 Weaviate 连接参数：

配置参数

配置界面支持以下输入验证：

• URL 格式验证
• 端口范围检查（1-65535）
• API Key 长度检查

资料来源：README.md:部署配置章节

配置数据模型

后端类型定义

Verba 后端使用 Python 定义了配置相关的数据结构：

# RAG 配置模型
class RAGConfig:
    components: Dict[str, Component]
    
# 凭证模型  
class Credentials:
    url: str
    deployment: str
    api_key: Optional[str]

前端类型映射

资料来源：frontend/app/types.ts 资料来源：goldenverba/server/types.py

环境配置工作流

首次启动配置流程

sequenceDiagram
    participant User as 用户
    participant Frontend as 前端
    participant Backend as 后端
    
    User->>Frontend: 选择部署类型
    Frontend->>Backend: 发送连接请求
    Backend->>Weaviate: 验证连接
    Weaviate-->>Backend: 连接结果
    Backend-->>Frontend: 返回凭证
    Frontend->>User: 显示配置界面

生产环境配置

对于生产环境部署，建议通过以下方式配置：

1. 设置默认部署：使用 DEFAULT_DEPLOYMENT 环境变量
2. 配置 API 密钥：在 Custom 部署模式下启用认证
3. 配置 CORS：允许指定的域名访问

版本兼容性

Verba 的 Python 版本要求与依赖兼容：

资料来源：setup.py:11

最佳实践

开发环境配置

# .env 文件示例
DEFAULT_DEPLOYMENT=Local
OLLAMA_MODEL=llama2
OLLAMA_EMBED_MODEL=nomic-embed-text

生产环境配置

# 生产环境建议
DEFAULT_DEPLOYMENT=Custom
WEAVIATE_URL=https://your-instance.weaviate.cloud
WEAVIATE_API_KEY=your-api-key

容器化部署

使用 Docker 部署时，确保环境变量正确传递给容器：

docker run -e DEFAULT_DEPLOYMENT=Docker \
           -e WEAVIATE_URL=http://weaviate:8080 \
           verba:latest

常见问题

Q: 如何跳过部署选择界面？

A: 设置 DEFAULT_DEPLOYMENT 环境变量为 Local、Docker、Weaviate 或 Custom 即可跳过选择步骤。

Q: Custom 部署需要哪些信息？

A: 需要提供 Weaviate 实例的 URL、端口和可选的 API 密钥。

Q: 支持哪些 Weaviate 客户端版本？

A: Verba 2.1.3 当前使用 weaviate-client==4.9.6。

Pitfall Log / 踩坑日志

项目：weaviate/Verba

摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：1.0.1 Beautiful Verba。

1. 安装坑 · 来源证据：1.0.1 Beautiful Verba

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.0.1 Beautiful Verba
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b08b22b1d7404da6ae9d8153c53602cd | https://github.com/weaviate/Verba/releases/tag/1.0.0 | 来源类型 github_release 暴露的待验证使用条件。

2. 安装坑 · 来源证据：v0.4.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.4.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_199393ab54bc4fd79d576c42dc3198f2 | https://github.com/weaviate/Verba/releases/tag/0.4.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：v1.0.3

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.3
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_90c577983a844f3ba246a181a8e03997 | https://github.com/weaviate/Verba/releases/tag/v1.0.3 | 来源类型 github_release 暴露的待验证使用条件。

4. 安装坑 · 来源证据：v2.1.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_0ec01ecbe8494b08a039e08f6bf68f01 | https://github.com/weaviate/Verba/releases/tag/v2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:672002598 | https://github.com/weaviate/Verba | README/documentation is current enough for a first validation pass.

6. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | last_activity_observed missing

7. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:672002598 | https://github.com/weaviate/Verba | no_demo; severity=medium

8. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:672002598 | https://github.com/weaviate/Verba | No sandbox install has been executed yet; downstream must verify before user use.

9. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:672002598 | https://github.com/weaviate/Verba | no_demo; severity=medium

10. 安全/权限坑 · 来源证据：v0.3.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.3.0
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_29616574b8474fb7a44c6d3350b062fd | https://github.com/weaviate/Verba/releases/tag/0.3.0 | 来源类型 github_release 暴露的待验证使用条件。

11. 安全/权限坑 · 来源证据：v0.3.1

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.3.1
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8c5e79dc1cf3480b9792cbd54643bb14 | https://github.com/weaviate/Verba/releases/tag/0.3.1 | 来源类型 github_release 暴露的待验证使用条件。

12. 安全/权限坑 · 来源证据：v2.1.2

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.2
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9dc754c525ec48808ee74f66f9694312 | https://github.com/weaviate/Verba/releases/tag/v2.1.2 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

13. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | issue_or_pr_quality=unknown

14. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | release_recency=unknown