{
  "canonical_name": "weaviate/Verba",
  "compilation_id": "pack_3d61a39da149459d9d7759f75a51f35f",
  "created_at": "2026-05-15T16:18:08.435385+00:00",
  "created_by": "project-pack-compiler",
  "feedback": {
    "carrier_selection_notes": [
      "viable_asset_types=skill, recipe, host_instruction, eval, preflight",
      "recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
    ],
    "evidence_delta": {
      "confirmed_claims": [
        "identity_anchor_present",
        "capability_and_host_targets_present",
        "install_path_declared_or_better"
      ],
      "missing_required_fields": [],
      "must_verify_forwarded": [
        "Run or inspect `pip install goldenverba` in an isolated environment.",
        "Confirm the project exposes the claimed capability to at least one target host."
      ],
      "quickstart_execution_scope": "allowlisted_sandbox_smoke",
      "sandbox_command": "pip install goldenverba",
      "sandbox_container_image": "python:3.12-slim",
      "sandbox_execution_backend": "docker",
      "sandbox_planner_decision": "llm_execute_isolated_install",
      "sandbox_validation_id": "sbx_df8bbf5a74b743af9b888ee80ad8294b"
    },
    "feedback_event_type": "project_pack_compilation_feedback",
    "learning_candidate_reasons": [],
    "template_gaps": []
  },
  "identity": {
    "canonical_id": "project_c0f1a886172a9e79390a60dab1bb84b3",
    "canonical_name": "weaviate/Verba",
    "homepage_url": null,
    "license": "unknown",
    "repo_url": "https://github.com/weaviate/Verba",
    "slug": "verba",
    "source_packet_id": "phit_8e9dac6373e241948b80a473ca9e3367",
    "source_validation_id": "dval_5a4f2866bee9484d877f3814456e0372"
  },
  "merchandising": {
    "best_for": "需要信息检索与知识管理能力，并使用 local_cli的用户",
    "github_forks": 848,
    "github_stars": 7694,
    "one_liner_en": "Retrieval Augmented Generation (RAG) chatbot powered by Weaviate",
    "one_liner_zh": "Retrieval Augmented Generation (RAG) chatbot powered by Weaviate",
    "primary_category": {
      "category_id": "research-knowledge",
      "confidence": "medium",
      "name_en": "Research & Knowledge",
      "name_zh": "信息检索与知识管理",
      "reason": "matched_keywords:rag, retrieval"
    },
    "target_user": "使用 local_cli 等宿主 AI 的用户",
    "title_en": "Verba",
    "title_zh": "Verba 能力包",
    "visible_tags": [
      {
        "label_en": "Knowledge Retrieval",
        "label_zh": "知识检索",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "product_domain-knowledge-retrieval",
        "type": "product_domain"
      },
      {
        "label_en": "Knowledge Base Q&A",
        "label_zh": "知识库问答",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "user_job-knowledge-base-q-a",
        "type": "user_job"
      },
      {
        "label_en": "Workflow Automation",
        "label_zh": "流程自动化",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "core_capability-workflow-automation",
        "type": "core_capability"
      },
      {
        "label_en": "Node-based Workflow",
        "label_zh": "节点式流程编排",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "workflow_pattern-node-based-workflow",
        "type": "workflow_pattern"
      },
      {
        "label_en": "Evaluation Suite",
        "label_zh": "评测体系",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "selection_signal-evaluation-suite",
        "type": "selection_signal"
      }
    ]
  },
  "packet_id": "phit_8e9dac6373e241948b80a473ca9e3367",
  "page_model": {
    "artifacts": {
      "artifact_slug": "verba",
      "files": [
        "PROJECT_PACK.json",
        "QUICK_START.md",
        "PROMPT_PREVIEW.md",
        "HUMAN_MANUAL.md",
        "AI_CONTEXT_PACK.md",
        "BOUNDARY_RISK_CARD.md",
        "PITFALL_LOG.md",
        "REPO_INSPECTION.json",
        "REPO_INSPECTION.md",
        "CAPABILITY_CONTRACT.json",
        "EVIDENCE_INDEX.json",
        "CLAIM_GRAPH.json"
      ],
      "required_files": [
        "PROJECT_PACK.json",
        "QUICK_START.md",
        "PROMPT_PREVIEW.md",
        "HUMAN_MANUAL.md",
        "AI_CONTEXT_PACK.md",
        "BOUNDARY_RISK_CARD.md",
        "PITFALL_LOG.md",
        "REPO_INSPECTION.json"
      ]
    },
    "detail": {
      "capability_source": "Project Hit Packet + DownstreamValidationResult",
      "commands": [
        {
          "command": "pip install goldenverba",
          "label": "Python / pip · 官方安装入口",
          "source": "https://github.com/weaviate/Verba#readme",
          "verified": true
        }
      ],
      "display_tags": [
        "知识检索",
        "知识库问答",
        "流程自动化",
        "节点式流程编排",
        "评测体系"
      ],
      "eyebrow": "信息检索与知识管理",
      "glance": [
        {
          "body": "判断自己是不是目标用户。",
          "label": "最适合谁",
          "value": "需要信息检索与知识管理能力，并使用 local_cli的用户"
        },
        {
          "body": "先理解能力边界，再决定是否继续。",
          "label": "核心价值",
          "value": "Retrieval Augmented Generation (RAG) chatbot powered by Weaviate"
        },
        {
          "body": "未完成验证前保持审慎。",
          "label": "继续前",
          "value": "publish to Doramagic.ai project surfaces"
        }
      ],
      "guardrail_source": "Boundary & Risk Card",
      "guardrails": [
        {
          "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
          "label": "Check 1",
          "value": "不要把试用当真实运行"
        },
        {
          "body": "local_cli",
          "label": "Check 2",
          "value": "确认宿主兼容"
        },
        {
          "body": "publish to Doramagic.ai project surfaces",
          "label": "Check 3",
          "value": "先隔离验证"
        }
      ],
      "mode": "skill, recipe, host_instruction, eval, preflight",
      "pitfall_log": {
        "items": [
          {
            "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.0.1 Beautiful Verba",
            "category": "安装坑",
            "evidence": [
              "community_evidence:github | cevd_b08b22b1d7404da6ae9d8153c53602cd | https://github.com/weaviate/Verba/releases/tag/1.0.0 | 来源类型 github_release 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：1.0.1 Beautiful Verba",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.4.0",
            "category": "安装坑",
            "evidence": [
              "community_evidence:github | cevd_199393ab54bc4fd79d576c42dc3198f2 | https://github.com/weaviate/Verba/releases/tag/0.4.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v0.4.0",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.3",
            "category": "安装坑",
            "evidence": [
              "community_evidence:github | cevd_90c577983a844f3ba246a181a8e03997 | https://github.com/weaviate/Verba/releases/tag/v1.0.3 | 来源类型 github_release 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v1.0.3",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0",
            "category": "安装坑",
            "evidence": [
              "community_evidence:github | cevd_0ec01ecbe8494b08a039e08f6bf68f01 | https://github.com/weaviate/Verba/releases/tag/v2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v2.1.0",
            "user_impact": "可能增加新用户试用和生产接入成本。"
          },
          {
            "body": "README/documentation is current enough for a first validation pass.",
            "category": "能力坑",
            "evidence": [
              "capability.assumptions | github_repo:672002598 | https://github.com/weaviate/Verba | README/documentation is current enough for a first validation pass."
            ],
            "severity": "medium",
            "suggested_check": "将假设转成下游验证清单。",
            "title": "能力判断依赖假设",
            "user_impact": "假设不成立时，用户拿不到承诺的能力。"
          },
          {
            "body": "未记录 last_activity_observed。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | last_activity_observed missing"
            ],
            "severity": "medium",
            "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
            "title": "维护活跃度未知",
            "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "downstream_validation.risk_items | github_repo:672002598 | https://github.com/weaviate/Verba | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "进入安全/权限治理复核队列。",
            "title": "下游验证发现风险项",
            "user_impact": "下游已经要求复核，不能在页面中弱化。"
          },
          {
            "body": "No sandbox install has been executed yet; downstream must verify before user use.",
            "category": "安全/权限坑",
            "evidence": [
              "risks.safety_notes | github_repo:672002598 | https://github.com/weaviate/Verba | No sandbox install has been executed yet; downstream must verify before user use."
            ],
            "severity": "medium",
            "suggested_check": "转成明确权限清单和安全审查提示。",
            "title": "存在安全注意事项",
            "user_impact": "用户安装前需要知道权限边界和敏感操作。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "risks.scoring_risks | github_repo:672002598 | https://github.com/weaviate/Verba | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
            "title": "存在评分风险",
            "user_impact": "风险会影响是否适合普通用户安装。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.3.0",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_29616574b8474fb7a44c6d3350b062fd | https://github.com/weaviate/Verba/releases/tag/0.3.0 | 来源类型 github_release 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v0.3.0",
            "user_impact": "可能影响授权、密钥配置或安全边界。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.3.1",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_8c5e79dc1cf3480b9792cbd54643bb14 | https://github.com/weaviate/Verba/releases/tag/0.3.1 | 来源类型 github_release 暴露的待验证使用条件。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v0.3.1",
            "user_impact": "可能影响授权、密钥配置或安全边界。"
          },
          {
            "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.2",
            "category": "安全/权限坑",
            "evidence": [
              "community_evidence:github | cevd_9dc754c525ec48808ee74f66f9694312 | https://github.com/weaviate/Verba/releases/tag/v2.1.2 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。"
            ],
            "severity": "medium",
            "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
            "title": "来源证据：v2.1.2",
            "user_impact": "可能影响授权、密钥配置或安全边界。"
          },
          {
            "body": "issue_or_pr_quality=unknown。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | issue_or_pr_quality=unknown"
            ],
            "severity": "low",
            "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
            "title": "issue/PR 响应质量未知",
            "user_impact": "用户无法判断遇到问题后是否有人维护。"
          },
          {
            "body": "release_recency=unknown。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | release_recency=unknown"
            ],
            "severity": "low",
            "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
            "title": "发布节奏不明确",
            "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
          }
        ],
        "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
        "summary": "发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：1.0.1 Beautiful Verba。",
        "title": "踩坑日志"
      },
      "snapshot": {
        "contributors": 40,
        "forks": 848,
        "license": "unknown",
        "note": "站点快照，非实时质量证明；用于开工前背景判断。",
        "stars": 7694
      },
      "source_url": "https://github.com/weaviate/Verba",
      "steps": [
        {
          "body": "不安装项目，先体验能力节奏。",
          "code": "preview",
          "title": "先试 Prompt"
        },
        {
          "body": "理解输入、输出、失败模式和边界。",
          "code": "manual",
          "title": "读说明书"
        },
        {
          "body": "把上下文交给宿主 AI 继续工作。",
          "code": "context",
          "title": "带给 AI"
        },
        {
          "body": "进入主力环境前先完成安装入口与风险边界验证。",
          "code": "verify",
          "title": "沙箱验证"
        }
      ],
      "subtitle": "Retrieval Augmented Generation (RAG) chatbot powered by Weaviate",
      "title": "Verba 能力包",
      "trial_prompt": "# Verba - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for weaviate/Verba.\n\nProject:\n- Name: Verba\n- Repository: https://github.com/weaviate/Verba\n- Summary: Retrieval Augmented Generation (RAG) chatbot powered by Weaviate\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Retrieval Augmented Generation (RAG) chatbot powered by Weaviate\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Retrieval Augmented Generation (RAG) chatbot powered by Weaviate\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-introduction: Introduction to Verba. Produce one small intermediate artifact and wait for confirmation.\n2. page-rag-concepts: RAG Concepts in Verba. Produce one small intermediate artifact and wait for confirmation.\n3. page-component-architecture: Component Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. page-data-ingestion: Data Ingestion System. Produce one small intermediate artifact and wait for confirmation.\n5. page-chunking-strategies: Chunking Strategies. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/weaviate/Verba\n- https://github.com/weaviate/Verba#readme\n- README.md\n- CHANGELOG.md\n- goldenverba/verba_manager.py\n- goldenverba/components/interfaces.py\n- goldenverba/components/types.py\n- goldenverba/components/__init__.py\n- goldenverba/components/managers.py\n- goldenverba/components/reader/BasicReader.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
      "voices": [
        {
          "body": "来源平台：github。github/github_release: v2.1.2（https://github.com/weaviate/Verba/releases/tag/v2.1.2）；github/github_release: v2.1.0（https://github.com/weaviate/Verba/releases/tag/v2.1）；github/github_release: v1.0.3（https://github.com/weaviate/Verba/releases/tag/v1.0.3）；github/github_release: 1.0.1 Beautiful Verba（https://github.com/weaviate/Verba/releases/tag/1.0.0）；github/github_release: v0.4.0（https://github.com/weaviate/Verba/releases/tag/0.4.0）；github/github_release: v0.3.1（https://github.com/weaviate/Verba/releases/tag/0.3.1）；github/github_release: v0.3.0（https://github.com/weaviate/Verba/releases/tag/0.3.0）。这些是项目级外部声音，不作为单独质量证明。",
          "items": [
            {
              "kind": "github_release",
              "source": "github",
              "title": "v2.1.2",
              "url": "https://github.com/weaviate/Verba/releases/tag/v2.1.2"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v2.1.0",
              "url": "https://github.com/weaviate/Verba/releases/tag/v2.1"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v1.0.3",
              "url": "https://github.com/weaviate/Verba/releases/tag/v1.0.3"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "1.0.1 Beautiful Verba",
              "url": "https://github.com/weaviate/Verba/releases/tag/1.0.0"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v0.4.0",
              "url": "https://github.com/weaviate/Verba/releases/tag/0.4.0"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v0.3.1",
              "url": "https://github.com/weaviate/Verba/releases/tag/0.3.1"
            },
            {
              "kind": "github_release",
              "source": "github",
              "title": "v0.3.0",
              "url": "https://github.com/weaviate/Verba/releases/tag/0.3.0"
            }
          ],
          "status": "已收录 7 条来源",
          "title": "社区讨论"
        }
      ]
    },
    "homepage_card": {
      "category": "信息检索与知识管理",
      "desc": "Retrieval Augmented Generation (RAG) chatbot powered by Weaviate",
      "effort": "安装已验证",
      "forks": 848,
      "icon": "search",
      "name": "Verba 能力包",
      "risk": "可发布",
      "slug": "verba",
      "stars": 7694,
      "tags": [
        "知识检索",
        "知识库问答",
        "流程自动化",
        "节点式流程编排",
        "评测体系"
      ],
      "thumb": "blue",
      "type": "Skill Pack"
    },
    "manual": {
      "markdown": "# https://github.com/weaviate/Verba 项目说明书\n\n生成时间：2026-05-15 15:59:59 UTC\n\n## 目录\n\n- [Introduction to Verba](#page-introduction)\n- [RAG Concepts in Verba](#page-rag-concepts)\n- [Component Architecture](#page-component-architecture)\n- [Data Ingestion System](#page-data-ingestion)\n- [Chunking Strategies](#page-chunking-strategies)\n- [Embedding and Vector Storage](#page-embedding-system)\n- [RAG Retrieval System](#page-retrieval-system)\n- [LLM Generators and Answer Generation](#page-llm-generators)\n- [Embedder Configuration](#page-embedders)\n- [Frontend Component Overview](#page-frontend-components)\n\n<a id='page-introduction'></a>\n\n## Introduction to Verba\n\n### 相关页面\n\n相关主题：[RAG Concepts in Verba](#page-rag-concepts)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n- [frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n- [frontend/app/components/Login/GettingStarted.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/GettingStarted.tsx)\n- [frontend/app/components/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n- [frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n- [PYTHON_TUTORIAL.md](https://github.com/weaviate/Verba/blob/main/PYTHON_TUTORIAL.md)\n</details>\n\n# Introduction to Verba\n\n## Overview\n\nVerba (The Golden RAGtriever) is an open-source, user-friendly RAG (Retrieval-Augmented Generation) application developed by Weaviate. It provides a streamlined interface for building and interacting with vector databases, enabling users to explore datasets and extract insights through semantic search and generative AI capabilities.\n\nThe application is designed to be accessible to both technical and non-technical users, offering multiple deployment options and integration with various LLM providers. Verba supports Python versions 3.10.0 to 3.12.0 and is distributed as the `goldenverba` Python package.\n\n| Property | Value |\n|----------|-------|\n| **Package Name** | goldenverba |\n| **Current Version** | 2.1.3 |\n| **Python Support** | >=3.10.0, <3.13.0 |\n| **Repository** | https://github.com/weaviate/Verba |\n| **License** | BSD License |\n\n资料来源：[setup.py:3-14](https://github.com/weaviate/Verba/blob/main/setup.py)\n\n## Core Features\n\nVerba provides a comprehensive set of features for RAG-based applications:\n\n### Data Import and Management\n\nUsers can import documents through multiple methods:\n- **Add Files**: Upload individual files directly\n- **Add Directory**: Import entire folders of documents\n- **Add URL**: Fetch content from web sources\n\nThe system automatically chunks and processes documents, making them searchable and queryable. Supported file formats include text files, PDFs, CSV, XLSX, and XLS formats for the DefaultReader.\n\n资料来源：[README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n\n### Chat Interface\n\nThe Chat page enables users to ask questions about their imported data. The system retrieves relevant document chunks and generates contextual responses using the configured LLM. The chat interface displays:\n\n- Real-time retrieval and generation status\n- Cached results indicator for faster subsequent queries\n- Source attribution for retrieved information\n- Code block syntax highlighting in responses\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n\n### Document Explorer\n\nUsers can browse, view, and manage imported documents through the Document Explorer. Each document displays:\n\n- Document metadata and labels\n- Chunk information with relevancy scores\n- Source links for reference\n- Content preview with Markdown rendering\n\n资料来源：[frontend/app/components/Document/ContentView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Document/ContentView.tsx)\n\n### Configuration Options\n\nVerba allows granular configuration of the RAG pipeline, including:\n\n- LLM provider selection\n- Embedding model configuration\n- Retrieval parameters\n- Chunk size and overlap settings\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n    A[User Interface - React Frontend] --> B[FastAPI Backend Server]\n    B --> C[Verba Manager - Core Logic]\n    C --> D[Weaviate Vector Database]\n    \n    E[LLM Providers] --> B\n    F[Ollama / HuggingFace] --> B\n    \n    G[Document Readers] --> C\n    H[Embedders] --> C\n    I[Generators] --> C\n    \n    D --> G\n    D --> H\n    D --> I\n```\n\n## Deployment Options\n\nVerba supports four deployment configurations to accommodate different use cases and infrastructure requirements.\n\n| Deployment Type | Description | Use Case |\n|-----------------|-------------|----------|\n| **Weaviate** | Connect to Weaviate Cloud Services (WCS) | Production deployments with managed infrastructure |\n| **Docker** | Run with Docker Compose | Containerized deployments |\n| **Local** | Run entirely on local machine | Development and testing |\n| **Custom** | Specify custom Weaviate URL and credentials | Integration with existing Weaviate instances |\n\n资料来源：[frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n\n### Environment Variables\n\nConfiguration can be managed through environment variables for automated deployments:\n\n| Variable | Description |\n|----------|-------------|\n| `DEFAULT_DEPLOYMENT` | Pre-select deployment type (Local, Docker, Weaviate, Custom) |\n| `OLLAMA_MODEL` | Default Ollama model name |\n| `OLLAMA_EMBED_MODEL` | Default Ollama embedding model |\n\n资料来源：[CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n## Supported Integrations\n\n### LLM Providers\n\nVerba integrates with multiple LLM providers for text generation:\n\n- **OpenAI**: GPT models with dynamic model name retrieval based on API key and URL\n- **Anthropic**: Claude models\n- **Cohere**: Command models\n- **Groq**: Fast inference API\n- **Novita AI**: Additional generative capabilities\n- **Upstage**: Reader, Embedder, and Generator support\n\n资料来源：[README.md](https://github.com/weaviate/Verba/blob/main/README.md) and [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n### Embedding Providers\n\nFor vector embeddings, Verba supports:\n\n- **Ollama**: Local embedding models\n- **HuggingFace**: Sentence transformers and other models\n- **OpenAI**: text-embedding-ada-002 and newer models\n- **Upstage**: Solar embedding models\n\n### Document Readers\n\nThe system includes specialized readers for various file formats:\n\n- **AssemblyAI**: Audio file transcription and processing\n- **DefaultReader**: Text, PDF, CSV, XLSX, XLS formats\n- **Unstructured**: Advanced document parsing capabilities\n\n## Installation Methods\n\n### Install via pip\n\n```bash\npip install goldenverba\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/weaviate/Verba\ncd Verba\npip install -e .\n```\n\n### Deploy with Docker\n\n```bash\ngit clone https://github.com/weaviate/Verba\ndocker compose --env-file <your-env-file> up -d --build\n```\n\n资料来源：[README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n\n## Project Structure\n\nThe Verba project is organized into two main components:\n\n```\nVerba/\n├── goldenverba/          # Python backend package\n│   └── server/           # FastAPI server implementation\n├── frontend/             # React TypeScript frontend\n│   └── app/\n│       ├── components/   # React components\n│       │   ├── Chat/     # Chat interface components\n│       │   ├── Document/ # Document explorer components\n│       │   ├── Ingestion/# Data import components\n│       │   ├── Login/    # Authentication views\n│       │   ├── Navigation/ # Navigation components\n│       │   └── Settings/ # Configuration components\n│       └── page.tsx      # Main application page\n├── setup.py              # Package configuration\n└── README.md             # Project documentation\n```\n\n## User Interface Navigation\n\nThe main navigation includes the following sections:\n\n| Navigation Item | Description |\n|-----------------|-------------|\n| **Chat** | Query imported data using RAG |\n| **Documents** | Browse and manage imported documents |\n| **Import Data** | Add new files, directories, or URLs |\n| **Settings** | Configure Verba and manage collections |\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n\n## Settings and Management\n\nThe Settings page provides administrative functions for Verba management:\n\n### Collections Management\n\nView all Weaviate collections with their object counts and status information, including shard configuration.\n\n### Reset Operations\n\n| Operation | Description |\n|-----------|-------------|\n| **Reset Documents** | Clears all documents and chunks from Verba |\n| **Reset Config** | Resets configuration to default values |\n| **Reset Verba** | Deletes all Verba-related collections |\n| **Reset Suggestions** | Clears autocomplete suggestion data |\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Settings/InfoView.tsx)\n\n## Getting Started Workflow\n\n```mermaid\ngraph LR\n    A[Install Verba] --> B[Configure Deployment]\n    B --> C[Set API Keys]\n    C --> D[Import Data]\n    D --> E[Configure RAG Pipeline]\n    E --> F[Query Data]\n```\n\n1. **Installation**: Choose an installation method (pip, source, or Docker)\n2. **Deployment Configuration**: Select deployment type (Weaviate, Docker, Local, or Custom)\n3. **API Keys**: Configure required API keys in `.env` file or through the UI\n4. **Data Import**: Import documents using Add Files, Add Directory, or Add URL\n5. **Configuration**: Adjust RAG pipeline settings under the Config tab\n6. **Query**: Ask questions and receive answers with relevant document citations\n\n资料来源：[README.md](https://github.com/weaviate/Verba/blob/main/README.md) and [frontend/app/components/Login/GettingStarted.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/GettingStarted.tsx)\n\n## Version History\n\n| Version | Release | Key Features |\n|---------|---------|--------------|\n| 2.1.3 | Latest | OLLAMA_MODEL, OLLAMA_EMBED_MODEL env vars, CSV/XLSX/XLS support, Hiding Getting Started display |\n| 2.1.2 | Previous | Novita Generator support, basic Document class tests, spaCy fixes |\n| 2.1.1 | Earlier | Dynamic OpenAI model retrieval |\n| 2.1.0 | Earlier | Upstage integration, Custom deployment, Groq support, AssemblyAI Reader |\n\n资料来源：[CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n## External Resources\n\n| Resource | URL |\n|----------|-----|\n| GitHub Repository | https://github.com/weaviate/Verba |\n| Blog Post | https://weaviate.io/blog/verba-open-source-rag-app |\n| Video Tutorial | https://www.youtube.com/watch?v=swKKRdLBhas |\n| Weaviate Forum | https://forum.weaviate.io/ |\n\n## Contributing\n\nVerba is an open-source community project. Contributions are welcome through:\n\n- GitHub Issues for bug reports\n- GitHub Discussions for feature requests and ideas\n- Pull Requests for code contributions\n\nBefore contributing, please review the Contribution Guide in the repository.\n\n---\n\n<a id='page-rag-concepts'></a>\n\n## RAG Concepts in Verba\n\n### 相关页面\n\n相关主题：[Introduction to Verba](#page-introduction), [RAG Retrieval System](#page-retrieval-system), [LLM Generators and Answer Generation](#page-llm-generators)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n- [frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n- [frontend/app/components/Chat/ChatMessage.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatMessage.tsx)\n- [frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n- [frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n</details>\n\n# RAG Concepts in Verba\n\nVerba (The Golden RAGtriever) is an open-source RAG (Retrieval-Augmented Generation) application designed to provide a streamlined, user-friendly interface for building and interacting with RAG-powered applications. This document explains the core RAG concepts implemented within Verba's architecture.\n\n## What is RAG?\n\nRetrieval-Augmented Generation (RAG) is a pattern that combines the power of large language models (LLMs) with external knowledge retrieval. Instead of relying solely on a model's training data, RAG systems:\n\n1. **Retrieve** relevant documents or chunks from a knowledge base\n2. **Augment** the user's query with the retrieved context\n3. **Generate** a response using the LLM with the augmented input\n\n资料来源：[README.md:1]()\n\n## Verba's RAG Pipeline Architecture\n\nVerba implements a complete RAG pipeline with configurable components for reading, embedding, chunking, and generating.\n\n```mermaid\ngraph TD\n    A[User Query] --> B[Retrieval Phase]\n    B --> C[Vector Search in Weaviate]\n    C --> D[Retrieve Relevant Chunks]\n    D --> E[Augment Query with Context]\n    E --> F[Generation Phase]\n    F --> G[LLM Response]\n    \n    H[Document Ingestion] --> I[Readers]\n    I --> J[Chunking]\n    J --> K[Embedding]\n    K --> L[Vector Storage in Weaviate]\n```\n\n资料来源：[README.md:1]()\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:1]()\n\n## Core Components\n\n### Readers\n\nVerba supports multiple document formats through its reader system. Documents can be imported via the frontend and processed by appropriate readers.\n\n| File Type | Format | Support Status |\n|-----------|--------|----------------|\n| CSV | `csv` | Supported (v2.1.3+) |\n| Excel | `xlsx`, `xls` | Supported (v2.1.3+) |\n| Text | Plain text | Supported |\n| Markdown | `.md` | Supported |\n| PDF | `.pdf` | Supported |\n| Audio | Various | Supported via AssemblyAI |\n\n资料来源：[CHANGELOG.md:8-13]()\n\n### Embedders\n\nVerba supports multiple embedding providers for converting documents into vector representations:\n\n- **OpenAI** - Uses OpenAI's embedding models\n- **Ollama** - Local embeddings via Ollama\n- **HuggingFace** - Sentence transformers from HuggingFace\n- **Cohere** - Cohere's embedding models\n- **Upstage** - Upstage's embedding service\n\n资料来源：[README.md:1]()\n资料来源：[CHANGELOG.md:15-22]()\n\n### Generators\n\nMultiple LLM providers are supported for generating responses:\n\n| Provider | Type | Configuration |\n|----------|------|---------------|\n| OpenAI | Cloud | API Key required |\n| Anthropic | Cloud | API Key required |\n| Cohere | Cloud | API Key required |\n| Groq | Cloud | API Key required |\n| Novita | Cloud | API Key required (v2.1.2+) |\n| Ollama | Local | No API Key needed |\n| Upstage | Cloud | API Key required |\n\n资料来源：[CHANGELOG.md:15-22]()\n资料来源：[frontend/app/components/Login/LoginView.tsx:1]()\n\n## Document Ingestion Workflow\n\nWhen users import documents into Verba, the following workflow is executed:\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Frontend\n    participant Reader\n    participant Chunker\n    participant Embedder\n    participant Weaviate\n    \n    User->>Frontend: Upload Document\n    Frontend->>Reader: Process File\n    Reader->>Chunker: Raw Text\n    Chunker->>Embedder: Text Chunks\n    Embedder->>Weaviate: Vector Embeddings\n    Weaviate->>Weaviate: Store Chunks + Vectors\n```\n\n### Chunking Configuration\n\nDocuments are split into manageable chunks for retrieval. Each chunk contains:\n\n- **Content** - The text content\n- **Chunk ID** - Position in original document\n- **Labels** - User-defined labels for categorization\n- **Source Link** - Reference to original document location\n- **Metadata** - Additional document properties\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1]()\n\n## Retrieval and Query Flow\n\n### Chat Interface\n\nVerba's chat interface handles the retrieval and generation process:\n\n```mermaid\ngraph LR\n    A[User Input] --> B[Socket Connection]\n    B --> C{Retrieval Phase}\n    C -->|Fetching Status: CHUNKS| D[Vector Search]\n    D --> E[Retrieve Top-K Chunks]\n    E --> F{Generation Phase}\n    F -->|Fetching Status: RESPONSE| G[LLM Processing]\n    G --> H[Stream Response]\n    H --> I[Display to User]\n```\n\nThe chat interface displays retrieval status to users:\n\n```typescript\nfetchingStatus === \"CHUNKS\" → \"Retrieving...\"\nfetchingStatus === \"RESPONSE\" → \"Generating...\"\n```\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:1]()\n\n### Message Types\n\nVerba supports multiple message types in the chat:\n\n| Type | Direction | Description |\n|------|-----------|-------------|\n| `user` | User → System | User queries |\n| `system` | System → User | LLM responses |\n| `error` | System → User | Error messages |\n| `retrieval` | System → User | Retrieved context |\n| `cached` | System → User | Cached responses |\n\n资料来源：[frontend/app/components/Chat/ChatMessage.tsx:1]()\n\n### Relevancy Scoring\n\nRetrieved chunks are scored for relevance. Chunks with a score greater than 0 are flagged as \"High Relevancy\":\n\n```tsx\n{contentSnippet.score > 0 && (\n  <div className=\"flex gap-2 items-center p-3 bg-primary-verba rounded-full w-fit\">\n    <HiSparkles size={12} />\n    <p className=\"text-xs flex text-text-verba\">High Relevancy</p>\n  </div>\n)}\n```\n\n资料来源：[frontend/app/components/Document/ContentView.tsx:1]()\n\n## Deployment Options\n\nVerba supports multiple deployment configurations:\n\n| Deployment | Description | Use Case |\n|------------|-------------|----------|\n| **Local** | Runs entirely on local machine with Ollama | Development, Privacy |\n| **Docker** | Containerized deployment | Easy setup |\n| **Weaviate Cloud** | Managed Weaviate service | Production |\n| **Custom** | User-provided Weaviate instance | Enterprise |\n\n资料来源：[README.md:1]()\n资料来源：[frontend/app/components/Login/LoginView.tsx:1]()\n\n### Environment Variables\n\nKey environment variables for RAG configuration:\n\n| Variable | Description |\n|----------|-------------|\n| `OLLAMA_MODEL` | Default Ollama model |\n| `OLLAMA_EMBED_MODEL` | Ollama embedding model |\n| `DEFAULT_DEPLOYMENT` | Default deployment type |\n| `WEAVIATE_URL` | Weaviate instance URL |\n| `WEAVIATE_API_KEY` | Weaviate API key |\n\n资料来源：[CHANGELOG.md:8-13]()\n\n## Configuration Management\n\nThe RAG pipeline can be configured through the Settings interface:\n\n```mermaid\ngraph TD\n    A[Settings Page] --> B[Config Tab]\n    A --> C[Info Tab]\n    A --> D[Collections Tab]\n    \n    B --> E[RAG Pipeline Settings]\n    C --> F[System Information]\n    D --> G[Weaviate Collections]\n    \n    E --> H[Embedder Selection]\n    E --> I[Generator Selection]\n    E --> J[Retrieval Settings]\n```\n\n### Configurable Options\n\n- **Embedder** - Choose embedding provider and model\n- **Generator** - Select LLM provider and model\n- **Retrieval** - Configure top-k, similarity thresholds\n- **Chunk Size** - Adjust document chunking parameters\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:1]()\n\n## Data Storage\n\n### Weaviate Collections\n\nVerba automatically creates collections in Weaviate for:\n\n- **Documents** - Original document metadata\n- **Chunks** - Vectorized document chunks with embeddings\n- **Configurations** - RAG pipeline settings\n\nEach collection tracks:\n- Object count\n- Shard configuration\n- Status\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:1]()\n\n## Reset Operations\n\nVerba provides granular reset capabilities:\n\n| Operation | Scope | Action |\n|-----------|-------|--------|\n| Reset Documents | Data | Clears all documents and chunks |\n| Reset Config | Configuration | Restores default RAG settings |\n| Reset Verba | System | Deletes all Verba collections |\n| Reset Suggestions | UI | Clears autocomplete cache |\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:1]()\n\n## Summary\n\nVerba implements a complete RAG pipeline with:\n\n- **Multi-format document support** - CSV, Excel, PDF, audio files\n- **Flexible embedding options** - Multiple cloud and local providers\n- **Diverse LLM integration** - OpenAI, Anthropic, Cohere, Ollama, and more\n- **Visual chat interface** - Real-time status updates during retrieval and generation\n- **Configurable pipeline** - Adjust chunking, embedding, and retrieval parameters\n- **Multiple deployment modes** - Local, Docker, Weaviate Cloud, or custom infrastructure\n\nThe system leverages Weaviate's vector database capabilities for efficient similarity search while providing a user-friendly interface for non-technical users to build and interact with RAG applications.\n\n---\n\n<a id='page-component-architecture'></a>\n\n## Component Architecture\n\n### 相关页面\n\n相关主题：[Data Ingestion System](#page-data-ingestion), [Chunking Strategies](#page-chunking-strategies), [Embedder Configuration](#page-embedders), [LLM Generators and Answer Generation](#page-llm-generators)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n- [frontend/app/components/Ingestion/FileSelectionView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/FileSelectionView.tsx)\n- [frontend/app/components/Settings/InfoView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Settings/InfoView.tsx)\n- [frontend/app/components/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n- [frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n- [README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n</details>\n\n# Component Architecture\n\n## Overview\n\nVerba (Golden RAGtriever) is a RAG (Retrieval-Augmented Generation) application built with a modular component architecture that separates concerns across ingestion, retrieval, and generation pipelines. The system enables users to import various data formats, process them into searchable chunks, and query them using configurable LLM-based chat interfaces. The frontend is built with React/Next.js and TypeScript, while the backend is powered by Python with FastAPI and Weaviate as the vector database.\n\nThe component architecture in Verba follows a plugin-based pattern where different readers, embedders, chunkers, and generators can be dynamically configured and swapped at runtime. This design allows extensibility without modifying core system code.\n\n## System Architecture\n\n```mermaid\ngraph TD\n    subgraph Frontend[\"Frontend (Next.js/React)\"]\n        Login[LoginView]\n        Chat[ChatInterface]\n        Ingest[FileSelectionView]\n        Settings[InfoView]\n        Nav[NavbarComponent]\n    end\n\n    subgraph Backend[\"Backend (Python/FastAPI)\"]\n        API[FastAPI Server]\n        Manager[Component Manager]\n        Components[Components Registry]\n    end\n\n    subgraph External[\"External Services\"]\n        Weaviate[Weaviate DB]\n        LLMs[LLM Providers]\n        Readers[Data Readers]\n    end\n\n    Login --> |Credentials| API\n    Chat --> |Query/RAGConfig| API\n    Ingest --> |FileData| API\n    Settings --> |Reset/Config| API\n    API --> Manager\n    Manager --> Components\n    Components --> Weaviate\n    Components --> LLMs\n    Components --> Readers\n```\n\n## Core Component Types\n\nVerba's component system is organized around four primary types that form the RAG pipeline:\n\n| Component Type | Purpose | Examples |\n|----------------|---------|----------|\n| **Reader** | Parse various data formats into text | DefaultReader, AssemblyAI, Unstructured |\n| **Embedder** | Convert text to vector representations | OpenAI Embedder, HuggingFace, Ollama |\n| **Chunker** | Split documents into manageable pieces | DefaultChunker |\n| **Generator** | Produce natural language responses | OpenAI Generator, Anthropic, Novita, Groq |\n\n## Component Manager Architecture\n\nThe component manager (`goldenverba/components/managers.py`) serves as the central registry and orchestrator for all pluggable components. It maintains references to available readers, embedders, chunkers, and generators, enabling runtime selection based on user configuration.\n\nComponents are registered through the `__init__.py` module which discovers and loads all available implementations. The manager provides methods to:\n\n- List available components by type\n- Retrieve component configurations\n- Instantiate components with provided settings\n- Validate component compatibility\n\n## Frontend Component Architecture\n\n### Navigation Structure\n\nThe frontend uses a page-based navigation system where `NavbarComponent` manages the main routing between different views:\n\n```mermaid\ngraph LR\n    Nav[NavbarComponent] --> |CHAT| ChatPage[ChatInterface]\n    Nav --> |DOCUMENTS| DocPage[DocumentExplorer]\n    Nav --> |ADD| AddPage[FileSelectionView]\n    Nav --> |SETTINGS| SettingsPage[InfoView]\n```\n\nNavigation items are conditionally rendered based on the `production` environment variable:\n\n- **Demo Mode**: Shows only Chat page\n- **Production/Local/Docker**: Shows Chat, Documents, Import Data, and Settings\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx]() (lines showing conditional rendering with `production != \"Demo\"`)\n\n### Login and Deployment Configuration\n\nThe `LoginView` component handles the initial setup flow, supporting multiple deployment types:\n\n| Deployment | Description | Configuration Required |\n|------------|-------------|----------------------|\n| Local | Standalone Weaviate instance | URL, API Key |\n| Docker | Containerized Weaviate | URL, API Key |\n| Weaviate Cloud (WCS) | Managed Weaviate service | URL, API Key |\n| Custom | User-specified Weaviate endpoint | URL, API Key, Port |\n\n资料来源：[frontend/app/components/Login/LoginView.tsx]() (lines 35-45 showing deployment type definitions)\n\n### Chat Interface Pipeline\n\nThe `ChatInterface` component implements the query-time RAG workflow:\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant ChatInterface\n    participant Backend\n    participant Weaviate\n    participant LLM\n    \n    User->>ChatInterface: Submit Query\n    ChatInterface->>Backend: /query with RAGConfig\n    Backend->>Weaviate: Vector Search\n    Weaviate->>Backend: Top-k Chunks\n    Backend->>LLM: Context + Query\n    LLM->>Backend: Generated Response\n    Backend->>ChatInterface: Response + Chunks\n    ChatInterface->>User: Display Results\n```\n\nThe interface displays retrieval status messages:\n- `CHUNKS` state: \"Retrieving...\" while fetching from Weaviate\n- `RESPONSE` state: \"Generating...\" while LLM produces answer\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx]() (lines showing fetchingStatus states)\n\n### Data Ingestion Flow\n\nThe `FileSelectionView` manages the document import pipeline:\n\n```mermaid\ngraph TD\n    Files[Files/Directories/URLs] --> Reader[Reader Component]\n    Reader --> Chunker[Chunker Component]\n    Chunker --> Embedder[Embedder Component]\n    Embedder --> Weaviate[Weaviate Collection]\n```\n\nFile imports support multiple sources:\n- **Add Files**: Individual file upload\n- **Add Directory**: Batch directory ingestion\n- **Add URL**: Web content extraction\n\n资料来源：[frontend/app/components/Ingestion/FileSelectionView.tsx]() (lines showing URL dropdown with Reader component filtering)\n\n### Settings and Configuration\n\nThe `InfoView` component provides system management capabilities:\n\n| Action | Function | Data Affected |\n|--------|----------|---------------|\n| Reset Documents | Clear all collections | Documents, Chunks |\n| Reset Config | Restore default settings | RAGConfig |\n| Reset Verba | Full system reset | All collections |\n| Reset Suggestions | Clear autocomplete cache | Suggestion data |\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx]() (lines showing UserModalComponent triggers)\n\n## RAG Configuration Schema\n\nThe `RAGConfig` object defines the active pipeline configuration:\n\n```typescript\ninterface RAGConfig {\n  Reader: {\n    components: Record<string, Component>;\n  };\n  Chunker: {\n    components: Record<string, Component>;\n  };\n  Embedder: {\n    components: Record<string, Component>;\n  };\n  Generator: {\n    components: Record<string, Component>;\n  };\n}\n```\n\nEach component contains:\n- `type`: Component category (e.g., \"URL\", \"Text\", \"Vector\")\n- `name`: Human-readable identifier\n- `settings`: Key-value configuration parameters\n\n## State Management\n\nVerba manages state through React props and context patterns:\n\n```mermaid\ngraph TD\n    App[App Root] --> |Credentials| LoginView\n    App --> |RAGConfig| ChatInterface\n    App --> |Themes| Components\n    App --> |production| NavbarComponent\n    \n    ChatInterface --> |setRAGConfig| App\n    LoginView --> |setIsLoggedIn| App\n```\n\nKey state objects:\n- **Credentials**: Weaviate connection details (URL, API key)\n- **RAGConfig**: Pipeline configuration for all component types\n- **Themes**: UI theming configuration\n- **production**: Deployment mode (\"Local\" | \"Demo\" | \"Production\")\n\n## Dependency Injection\n\nThe frontend components receive dependencies via constructor injection:\n\n```typescript\ninterface ChatInterfaceProps {\n  credentials: Credentials;\n  RAGConfig: RAGConfig | null;\n  setRAGConfig: (config: RAGConfig | null) => void;\n  production: \"Local\" | \"Demo\" | \"Production\";\n  addStatusMessage: (message: string) => void;\n}\n```\n\nThis pattern enables:\n- Testability through mock injection\n- Flexible component composition\n- Runtime configuration changes\n\n## WebSocket Communication\n\nReal-time updates between frontend and backend use WebSocket connections:\n\n- Connection status monitoring via `socketOnline` and `socketStatus`\n- Status updates: \"ONLINE\", \"OFFLINE\", \"CONNECTING\"\n- Ability to cancel ongoing operations (e.g., retrieval/generation)\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx]() (lines showing socket status handling)\n\n## Conclusion\n\nThe Verba component architecture demonstrates a clean separation between frontend presentation and backend processing, with a plugin-based system enabling flexible RAG pipeline configuration. The architecture supports multiple deployment scenarios, various data sources, and different LLM providers through abstracted component interfaces.\n\n---\n\n<a id='page-data-ingestion'></a>\n\n## Data Ingestion System\n\n### 相关页面\n\n相关主题：[Chunking Strategies](#page-chunking-strategies), [Embedding and Vector Storage](#page-embedding-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [goldenverba/components/document.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/document.py)\n- [goldenverba/components/reader/HTMLReader.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/reader/HTMLReader.py)\n- [frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n- [frontend/app/components/Ingestion/FileSelectionView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/FileSelectionView.tsx)\n- [frontend/app/components/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n</details>\n\n# Data Ingestion System\n\nThe Data Ingestion System in Verba (The Golden RAGtriever) is responsible for accepting user-provided documents from various sources, processing them through configurable reader pipelines, and preparing them for embedding and retrieval. This system forms the entry point of the RAG pipeline, enabling users to import files, URLs, directories, and audio content into the application.\n\n## System Overview\n\nThe ingestion system operates as a multi-stage pipeline that transforms raw content into structured `Document` objects ready for vectorization. It supports multiple input types and allows per-file configuration of chunking, embedding, and reading strategies.\n\nThe architecture consists of three primary layers:\n\n| Layer | Responsibility | Key Components |\n|-------|---------------|----------------|\n| **Frontend** | User interface for file selection and configuration | `FileSelectionView`, `BasicSettingView`, `NavbarComponent` |\n| **API** | Backend endpoint handling and request processing | `server/api.py` |\n| **Readers** | Content extraction from various file types and sources | `BasicReader`, `HTMLReader`, `UnstructuredAPI`, `AssemblyAIAPI`, etc. |\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:1-50]()\n\n## Ingestion Flow\n\n```mermaid\ngraph TD\n    A[User clicks Import Data] --> B[FileSelectionView]\n    B --> C{Input Type}\n    C -->|Files| D[Add Files Tab]\n    C -->|Directory| E[Add Directory Tab]\n    C -->|URLs| F[Add URL Tab]\n    D --> G[BasicSettingView - Configure]\n    E --> G\n    F --> G\n    G --> H[Select Reader Type]\n    G --> I[Set Chunker]\n    G --> J[Set Embedder]\n    G --> K[Add Metadata & Labels]\n    K --> L[Import Selected]\n    L --> M[API Endpoint: /import]\n    M --> N[Reader Processing]\n    N --> O[Document Creation]\n    O --> P[Chunking]\n    P --> Q[Vector Storage in Weaviate]\n```\n\n## Document Model\n\nThe core data structure used throughout ingestion is the `Document` class, defined in `goldenverba/components/document.py`. This class encapsulates all metadata and content associated with an ingested document.\n\n```python\nDocument(\n    title=str,\n    content=str,\n    extension=str,\n    labels=list,\n    source=str,\n    fileSize=int,\n    metadata=str,\n    meta=dict\n)\n```\n\n资料来源：[goldenverba/components/document.py:1-100]()\n\n### Document Creation from Configuration\n\nThe `create_document` function provides a factory method for generating `Document` objects from file configuration:\n\n```python\ndef create_document(content: str, fileConfig: FileConfig) -> Document:\n    return Document(\n        title=fileConfig.filename,\n        content=content,\n        extension=fileConfig.extension,\n        labels=fileConfig.labels,\n        source=fileConfig.source,\n        fileSize=fileConfig.file_size,\n        metadata=fileConfig.metadata,\n        meta={},\n    )\n```\n\n资料来源：[goldenverba/components/document.py:100-115]()\n\n## Reader Components\n\nReaders are responsible for extracting raw content from various input sources. Each reader implements a specific loading strategy and returns a list of `Document` objects.\n\n### Available Readers\n\n| Reader | Type | Supported Sources | Description |\n|--------|------|-------------------|-------------|\n| `BasicReader` | File | `.txt`, `.pdf`, `.docx`, `.xlsx`, `.xls`, `.csv` | Standard file reading for common document formats |\n| `HTMLReader` | URL | Web pages | Fetches and converts web pages, supports recursive crawling |\n| `UnstructuredAPI` | API | Multiple formats | Uses Unstructured.io API for complex document parsing |\n| `AssemblyAIAPI` | API | Audio files | Transcribes and extracts content from audio |\n| `GitReader` | Repository | Git repos | Clones and extracts documentation from Git repositories |\n| `UpstageDocumentParse` | API | Documents | Uses Upstage AI for document parsing |\n\n### HTMLReader Configuration\n\nThe HTMLReader supports advanced web scraping capabilities:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `URLs` | list | required | List of URLs to process |\n| `Convert To Markdown` | bool | true | Whether to convert HTML to markdown |\n| `Recursive` | bool | false | Whether to follow linked pages |\n| `Max Depth` | int | 3 | Maximum recursion depth for linked pages |\n\n资料来源：[goldenverba/components/reader/HTMLReader.py:1-80]()\n\n### HTMLReader Recursive Processing\n\n```python\nasync def process_url(\n    self,\n    url: str,\n    to_markdown: bool,\n    recursive: bool,\n    max_depth: int,\n    current_depth: int,\n    session: aiohttp.ClientSession,\n    reader: BasicReader,\n    fileConfig: FileConfig,\n    documents: List[Document],\n    processed_urls: set,\n):\n    if url in processed_urls or current_depth > max_depth:\n        return\n    \n    processed_urls.add(url)\n    # ... content fetching and document creation\n```\n\nThe reader uses an async pattern with `aiohttp.ClientSession` for efficient concurrent URL processing, maintaining a `processed_urls` set to prevent duplicate processing.\n\n资料来源：[goldenverba/components/reader/HTMLReader.py:80-120]()\n\n## Frontend Ingestion Interface\n\n### File Selection View\n\nThe `FileSelectionView` component provides the primary UI for selecting and managing files to ingest. It supports three input modes:\n\n```tsx\n<div className=\"tab-group\">\n  <Tabs \n    tabs={[\"Add Files\", \"Add Directory\", \"Add URL\"]}\n    onTabChange={handleTabChange}\n  />\n</div>\n```\n\nKey features include:\n- **File List Display**: Shows all selected files with their status\n- **Multi-file Selection**: Allows batch processing of multiple files\n- **URL Dropdown**: Provides reader type selection for URL inputs\n- **Import Actions**: Triggers the actual ingestion process\n\n资料来源：[frontend/app/components/Ingestion/FileSelectionView.tsx:1-100]()\n\n### Configuration Settings View\n\nThe `BasicSettingView` component provides per-file configuration options. Each file can have its own RAG pipeline configuration:\n\n| Setting | Description | UI Element |\n|---------|-------------|------------|\n| **Reader** | Content extraction method | Disabled text input showing selected reader |\n| **Chunker** | Text splitting strategy | Disabled text input with description |\n| **Embedder** | Vector embedding model | Disabled text input with description |\n| **Title** | Document display name | Editable text input |\n| **Source Link** | Original source reference | Editable text input |\n| **Labels** | Categorization tags | Input with add button |\n| **Metadata** | Custom key-value data | Textarea for JSON-like content |\n| **Overwrite** | Replace existing documents | Checkbox toggle |\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-150]()\n\n### Label Management\n\nLabels provide a way to categorize documents for filtering during retrieval:\n\n```tsx\n<input\n  type=\"text\"\n  value={label}\n  onChange={(e) => setLabel(e.target.value)}\n  onKeyDown={(e) => {\n    if (e.key === \"Enter\") {\n      e.preventDefault();\n      addLabel(label);\n    }\n  }}\n/>\n<VerbaButton\n  title=\"Add\"\n  Icon={IoAddCircleSharp}\n  onClick={() => addLabel(label)}\n/>\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:20-45]()\n\n### Debug Modal\n\nThe configuration includes a debug feature that displays the complete file configuration as JSON:\n\n```tsx\n<pre className=\"whitespace-pre-wrap text-xs\">\n  {selectedFileData\n    ? (() => {\n        const objCopy = { ...fileMap[selectedFileData] };\n        objCopy.content = \"File Content\";\n        return JSON.stringify(objCopy, null, 2);\n      })()\n    : \"\"}\n</pre>\n```\n\nThis allows users to inspect the full configuration state including the RAG pipeline settings before import.\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:100-130]()\n\n## Configuration Management\n\n### FileConfig Structure\n\nThe `FileConfig` object carries all configuration for a single file through the ingestion pipeline:\n\n| Field | Type | Purpose |\n|-------|------|---------|\n| `filename` | string | Document title |\n| `extension` | string | File type indicator |\n| `labels` | list | Categorization tags |\n| `source` | string | Original source URL/path |\n| `file_size` | int | Size in bytes |\n| `metadata` | string | Custom metadata string |\n| `rag_config` | dict | Reader, Chunker, Embedder settings |\n| `content` | string | Raw file content |\n| `overwrite` | bool | Whether to replace existing |\n\n### RAG Pipeline Configuration\n\nEach file maintains its own RAG configuration that specifies the processing pipeline:\n\n```tsx\nfileMap[selectedFileData].rag_config = {\n  \"Reader\": {\n    \"selected\": \"BasicReader\",\n    \"components\": {\n      \"BasicReader\": { \"type\": \"file\", \"description\": \"...\" },\n      \"HTMLReader\": { \"type\": \"URL\", \"description\": \"...\" }\n    }\n  },\n  \"Chunker\": {\n    \"selected\": \"DefaultChunker\",\n    \"components\": { ... }\n  },\n  \"Embedder\": {\n    \"selected\": \"OpenAIEmbedder\",\n    \"components\": { ... }\n  }\n}\n```\n\n## Navigation Integration\n\nThe ingestion system is accessible from the main navigation bar:\n\n```tsx\n{production != \"Demo\" && (\n  <NavbarButton\n    hide={false}\n    Icon={IoMdAddCircle}\n    title=\"Import Data\"\n    currentPage={currentPage}\n    setCurrentPage={setCurrentPage}\n    setPage=\"ADD\"\n  />\n)}\n```\n\nIn Demo mode, the import functionality is disabled to prevent unauthorized data ingestion.\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:30-45]()\n\n## State Management\n\nThe frontend maintains the ingestion state using React hooks:\n\n| State Variable | Type | Purpose |\n|---------------|------|---------|\n| `fileMap` | `Record<string, FileData>` | All files selected for ingestion |\n| `selectedFileData` | `string \\| null` | Currently selected file key |\n| `socketStatus` | `string` | Connection status to backend |\n| `currentPage` | `string` | Current navigation page |\n\nThe `FileData` interface contains both the raw content and the configuration:\n\n```tsx\ninterface FileData {\n  content: string;\n  filename: string;\n  extension: string;\n  labels: string[];\n  source: string;\n  file_size: number;\n  metadata: string;\n  rag_config: RAGConfig;\n  overwrite: boolean;\n  block: boolean;  // Disables editing during processing\n}\n```\n\n## Integration with RAG Pipeline\n\nAfter successful ingestion, documents flow into the RAG pipeline:\n\n1. **Reader** extracts raw content from the source\n2. **Chunker** splits content into smaller segments for retrieval\n3. **Embedder** converts chunks into vector embeddings\n4. **Weaviate** stores the embedded chunks for semantic search\n\nThis integration is configured per-file through the `rag_config` object, allowing different documents to use different processing strategies based on their content type or user requirements.\n\n## Error Handling\n\nThe HTMLReader demonstrates the error handling pattern used across readers:\n\n```python\nasync with aiohttp.ClientSession() as session:\n    for url in urls:\n        try:\n            await self.process_url(\n                url, to_markdown, recursive, max_depth,\n                0, session, reader, fileConfig, documents, processed_urls\n            )\n        except Exception as e:\n            msg.warn(f\"Failed to process URL {url}: {str(e)}\")\n```\n\nIndividual failures do not halt the entire ingestion process, allowing partial success scenarios.\n\n---\n\n<a id='page-chunking-strategies'></a>\n\n## Chunking Strategies\n\n### 相关页面\n\n相关主题：[Data Ingestion System](#page-data-ingestion), [Embedding and Vector Storage](#page-embedding-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [goldenverba/components/chunking/TokenChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/TokenChunker.py)\n- [goldenverba/components/chunking/SentenceChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/SentenceChunker.py)\n- [goldenverba/components/chunking/SemanticChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/SemanticChunker.py)\n- [goldenverba/components/chunking/RecursiveChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/RecursiveChunker.py)\n- [goldenverba/components/chunking/MarkdownChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/MarkdownChunker.py)\n- [goldenverba/components/chunking/HTMLChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/HTMLChunker.py)\n- [goldenverba/components/chunking/CodeChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/CodeChunker.py)\n- [goldenverba/components/chunking/JSONChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/JSONChunker.py)\n- [goldenverba/components/chunking/__init__.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/__init__.py)\n</details>\n\n# Chunking Strategies\n\n## Overview\n\nChunking strategies in Verba define how documents are split into smaller, semantically coherent units for embedding and retrieval. Each strategy implements the `Chunker` interface and provides different approaches to partitioning document content based on structural markers, token counts, sentence boundaries, or semantic similarity.\n\nThe chunking system is designed to:\n\n- Break large documents into manageable pieces for embedding\n- Preserve contextual continuity through overlapping chunks\n- Respect document structure (headers, code blocks, HTML tags)\n- Provide configuration options for fine-tuning chunk sizes and overlap\n- Skip documents that already contain chunks to avoid redundant processing\n\n资料来源：[goldenverba/components/chunking/__init__.py]()\n\n## Architecture\n\n### Chunker Interface\n\nAll chunkers inherit from the `Chunker` base class and implement the `chunk()` async method. The interface accepts configuration parameters, a list of documents, and an optional embedder.\n\n```python\nclass Chunker:\n    name: str\n    requires_library: list[str]\n    description: str\n\n    async def chunk(\n        self,\n        config: dict,\n        documents: list[Document],\n        embedder: Embedding | None = None,\n        embedder_config: dict | None = None,\n    ) -> list[Document]:\n```\n\n### Chunk Data Model\n\nEach chunk produced by the chunkers contains the following fields:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `content` | str | Full chunk text including overlap |\n| `chunk_id` | int | Sequential identifier within the document |\n| `start_i` | int \\| None | Character-level start index |\n| `end_i` | int \\| None | Character-level end index |\n| `content_without_overlap` | str | Chunk text without overlap region |\n\n资料来源：[goldenverba/components/chunk.py]()\n\n## Available Chunking Strategies\n\n### 1. Token Chunker\n\nThe Token Chunker splits documents based on token counts using spaCy's tokenizer. It ensures chunks align with natural token boundaries for efficient embedding.\n\n**Key Features:**\n\n- Splits text by token count using spaCy NLP\n- Configurable tokens per chunk via `Tokens` configuration\n- Configurable overlap via `Overlap` configuration\n- Calculates precise character-level indices for chunk boundaries\n\n**Configuration Options:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `Tokens` | int | Number of tokens per chunk |\n| `Overlap` | int | Number of overlapping tokens between chunks |\n\n**Behavior:**\n\n- If `Tokens` exceeds document length or is zero, the entire document becomes a single chunk\n- If overlap exceeds tokens, overlap is clamped to `tokens - 1` with a warning\n- Chunk content includes overlap; `content_without_overlap` excludes the overlap region\n\n资料来源：[goldenverba/components/chunking/TokenChunker.py]()\n\n### 2. Sentence Chunker\n\nThe Sentence Chunker splits documents at sentence boundaries using spaCy's sentence segmentation. This preserves complete sentences within chunks.\n\n**Key Features:**\n\n- Sentence-level splitting using spaCy's `sents` property\n- Configurable sentences per chunk\n- Configurable overlap at sentence level\n- Character-level index tracking for precise boundaries\n\n**Configuration Options:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `Sentences` | int | Number of sentences per chunk |\n| `Overlap` | int | Number of overlapping sentences between chunks |\n\n**Behavior:**\n\n- Extracts all sentences from the document using spaCy\n- Joins sentences to form chunks while preserving overlap regions\n- Calculates character offsets accounting for spacing between sentences\n\n资料来源：[goldenverba/components/chunking/SentenceChunker.py]()\n\n### 3. Recursive Chunker\n\nThe Recursive Chunker uses LangChain's `RecursiveCharacterTextSplitter` to intelligently split text while attempting to preserve natural boundaries.\n\n**Key Features:**\n\n- Multi-level character-based splitting\n- Preserves chunk boundaries at logical text breaks\n- Configurable chunk size and overlap\n- Uses `keep Separator` parameter to retain separators in chunks\n\n资料来源：[goldenverba/components/chunking/RecursiveChunker.py]()\n\n### 4. Semantic Chunker\n\nThe Semantic Chunker groups content based on semantic similarity rather than fixed sizes or boundaries.\n\n**Key Features:**\n\n- Clusters sentences by semantic meaning\n- Dynamically determines chunk boundaries based on content similarity\n- Optimal for maintaining topical coherence\n\n资料来源：[goldenverba/components/chunking/SemanticChunker.py]()\n\n### 5. Markdown Chunker\n\nThe Markdown Chunker splits documents based on markdown header hierarchy using LangChain's `MarkdownHeaderTextSplitter`.\n\n**Supported Headers:**\n\n| Header Level | Syntax |\n|--------------|--------|\n| Header 1 | `#` |\n| Header 2 | `##` |\n| Header 3 | `###` |\n\n**Key Features:**\n\n- Splits at markdown header boundaries\n- Preserves header context by prepending headers to each chunk\n- Uses `get_header_values()` helper to extract header text from LangChain document metadata\n- Maintains hierarchical context through header inclusion\n\n**Header Extraction Logic:**\n\n```python\ndef get_header_values(split_doc: LangChainDocument) -> list[str]:\n    header_keys = [header_key for _, header_key in HEADERS_TO_SPLIT_ON]\n    return [\n        header_value\n        for header_key in header_keys\n        if (header_value := split_doc.metadata.get(header_key)) is not None\n    ]\n```\n\n资料来源：[goldenverba/components/chunking/MarkdownChunker.py]()\n\n### 6. HTML Chunker\n\nThe HTML Chunker splits documents based on HTML tag structure using LangChain's `HTMLHeaderTextSplitter`.\n\n**Supported Tags:**\n\n| Tag | Description |\n|-----|-------------|\n| `h1` | Header 1 |\n| `h2` | Header 2 |\n| `h3` | Header 3 |\n| `h4` | Header 4 |\n\n**Key Features:**\n\n- Splits at HTML header boundaries\n- Preserves header content within each chunk\n- Appends header text before page content\n- Requires `langchain_text_splitters` library\n\n**Chunk Text Construction:**\n\n```python\nchunk_text = \"\"\nif len(chunk.metadata) > 0:\n    chunk_text += list(chunk.metadata.values())[0] + \"\\n\"\nchunk_text += chunk.page_content\n```\n\n资料来源：[goldenverba/components/chunking/HTMLChunker.py]()\n\n### 7. Code Chunker\n\nThe Code Chunker is optimized for source code files, splitting based on code-specific structures and syntax.\n\n**Key Features:**\n\n- Language-aware splitting for code files\n- Preserves code structure and syntax context\n- Handles various programming language conventions\n\n资料来源：[goldenverba/components/chunking/CodeChunker.py]()\n\n### 8. JSON Chunker\n\nThe JSON Chunker splits JSON documents at logical structural boundaries.\n\n**Key Features:**\n\n- Splits at JSON object/array boundaries\n- Preserves nested structure context\n- Handles JSON-specific formatting\n\n资料来源：[goldenverba/components/chunking/JSONChunker.py]()\n\n## Chunking Workflow\n\n```mermaid\ngraph TD\n    A[Document Ingestion] --> B{Already Chunked?}\n    B -->|Yes| C[Skip Chunking]\n    B -->|No| D[Select Chunker Strategy]\n    D --> E{Chunking Strategy}\n    E -->|Token| F[TokenChunker]\n    E -->|Sentence| G[SentenceChunker]\n    E -->|Recursive| H[RecursiveChunker]\n    E -->|Semantic| I[SemanticChunker]\n    E -->|Markdown| J[MarkdownChunker]\n    E -->|HTML| K[HTMLChunker]\n    E -->|Code| L[CodeChunker]\n    E -->|JSON| M[JSONChunker]\n    F --> N[Split Document]\n    G --> N\n    H --> N\n    I --> N\n    J --> N\n    K --> N\n    L --> N\n    M --> N\n    N --> O[Create Chunk Objects]\n    O --> P[Append to document.chunks]\n    P --> Q[Return Modified Documents]\n```\n\n## Chunking Configuration\n\nEach chunker accepts a configuration dictionary with strategy-specific parameters:\n\n| Chunker | Primary Config | Overlap Config | Library Dependency |\n|---------|----------------|-----------------|---------------------|\n| Token | `Tokens` | `Overlap` | `spacy` |\n| Sentence | `Sentences` | `Overlap` | `spacy` |\n| Recursive | `Chunk Size` | `Overlap` | `langchain_text_splitters` |\n| Semantic | N/A | N/A | `langchain_text_splitters` |\n| Markdown | N/A | N/A | `langchain_text_splitters` |\n| HTML | N/A | N/A | `langchain_text_splitters` |\n| Code | N/A | N/A | `langchain_text_splitters` |\n| JSON | N/A | N/A | `langchain_text_splitters` |\n\n## Overlap Strategy\n\nOverlap enables context preservation between adjacent chunks, improving retrieval accuracy for queries that span chunk boundaries.\n\n**Overlap Calculation in TokenChunker:**\n\n```python\nwhile i < len(doc):\n    start_i = i\n    end_i = min(i + units + overlap, len(doc))\n    if end_i == len(doc):\n        overlap_start = end_i\n    else:\n        overlap_start = min(i + units, end_i)\n\n    chunk_text = doc[start_i:end_i].text\n    chunk_text_without_overlap = doc[start_i:overlap_start].text\n```\n\n**Overlap Calculation in SentenceChunker:**\n\n```python\noverlap_start = max(0, end_i - overlap)\nchunk_text = \" \".join(sentences[start_i:end_i])\nchunk_text_without_overlap = \" \".join(sentences[start_i:overlap_start])\n```\n\n资料来源：[goldenverba/components/chunking/TokenChunker.py](), [goldenverba/components/chunking/SentenceChunker.py]()\n\n## Skip Mechanism\n\nAll chunkers implement a document skipping mechanism to prevent redundant processing:\n\n```python\n# Skip if document already contains chunks\nif len(document.chunks) > 0:\n    continue\n```\n\nThis ensures idempotent chunking operations and allows manual chunk management.\n\n## Best Practices\n\n### Choosing a Chunker\n\n| Document Type | Recommended Chunker | Reason |\n|---------------|---------------------|--------|\n| Plain text | Token, Sentence, Recursive | General-purpose splitting |\n| Markdown files | Markdown | Respects header hierarchy |\n| HTML documents | HTML | Preserves HTML structure |\n| Source code | Code | Language-aware boundaries |\n| JSON data | JSON | Structural preservation |\n| Long-form content | Semantic | Topic coherence |\n| Conversational data | Sentence | Natural language boundaries |\n\n### Configuration Guidelines\n\n1. **Token/Sentence counts**: Start with 256-512 tokens or 3-5 sentences per chunk\n2. **Overlap**: Use 10-20% overlap for most use cases\n3. **Boundary alignment**: For token-based chunking, prefer natural token boundaries over character cuts\n\n## Dependencies\n\n| Library | Used By | Purpose |\n|---------|---------|---------|\n| `spacy` | TokenChunker, SentenceChunker, RecursiveChunker | NLP processing, tokenization, sentence segmentation |\n| `langchain_text_splitters` | MarkdownChunker, HTMLChunker, CodeChunker, JSONChunker, RecursiveChunker, SemanticChunker | Text splitting algorithms |\n\n资料来源：[goldenverba/components/chunking/TokenChunker.py](), [goldenverba/components/chunking/MarkdownChunker.py](), [goldenverba/components/chunking/HTMLChunker.py]()\n\n---\n\n<a id='page-embedding-system'></a>\n\n## Embedding and Vector Storage\n\n### 相关页面\n\n相关主题：[Chunking Strategies](#page-chunking-strategies), [RAG Retrieval System](#page-retrieval-system)\n\n<details>\n<summary>Relevant Source Files</summary>\n\nThe following source files were used to generate this documentation page:\n\n- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n- [frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n- [frontend/app/components/Chat/ChatConfig.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatConfig.tsx)\n- [goldenverba/components/document.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/document.py)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n</details>\n\n# Embedding and Vector Storage\n\nVerba implements a modular RAG (Retrieval-Augmented Generation) pipeline where embeddings play a critical role in transforming textual content into vector representations for semantic search and retrieval operations.\n\n## Overview\n\nEmbedding and vector storage in Verba enables the transformation of documents and their chunks into high-dimensional vector representations. These vectors power semantic search capabilities, allowing users to retrieve relevant content based on meaning rather than exact keyword matches. The system supports multiple embedding providers and integrates with Weaviate as the primary vector database.\n\n## Architecture\n\n```mermaid\ngraph TD\n    A[Document] --> B[Reader Component]\n    B --> C[Text Content]\n    C --> D[Chunker Component]\n    D --> E[Document Chunks]\n    E --> F[Embedder Component]\n    F --> G[Vector Embeddings]\n    G --> H[Weaviate Vector Store]\n    \n    I[User Query] --> J[Embedder Component]\n    J --> K[Query Vector]\n    K --> H\n    H --> L[Similarity Search]\n    L --> M[Retrieved Chunks]\n```\n\n## Embedder Components\n\nVerba supports multiple embedder implementations, allowing users to choose the provider that best fits their requirements.\n\n### Available Embedders\n\n| Embedder | Provider | Status |\n|----------|----------|--------|\n| OpenAI Embedder | OpenAI | Default |\n| Cohere Embedder | Cohere | Supported |\n| Ollama Embedder | Ollama | Supported |\n| SentenceTransformers Embedder | HuggingFace | Supported |\n| VoyageAI Embedder | VoyageAI | Supported |\n| Upstage Embedder | Upstage | Supported |\n| Google Embedder | Google | Supported |\n| Weaviate Embedder | Weaviate | Built-in |\n\n资料来源：[CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n### Embedder Selection\n\nThe embedder can be configured through the RAG configuration interface:\n\n```typescript\n<ComponentView\n  RAGConfig={RAGConfig}\n  component_name=\"Embedder\"\n  selectComponent={selectComponent}\n  updateConfig={updateConfig}\n  saveComponentConfig={saveComponentConfig}\n  blocked={production == \"Demo\"}\n/>\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatConfig.tsx)\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `OPENAI_API_KEY` | API key for OpenAI embeddings | For OpenAI |\n| `OPENAI_EMBED_API_KEY` | Separate API key for embeddings | Optional |\n| `OPENAI_EMBED_BASE_URL` | Custom endpoint for embeddings | Optional |\n| `OPENAI_CUSTOM_EMBED` | Flag for custom embedding models | Optional |\n| `COHERE_API_KEY` | API key for Cohere | For Cohere |\n| `VOYAGE_API_KEY` | API key for VoyageAI | For VoyageAI |\n| `UPSTAGE_API_KEY` | API key for Upstage | For Upstage |\n| `GOOGLE_API_KEY` | API key for Google | For Google |\n\n资料来源：[README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n\n### Custom OpenAI Embedding Configuration\n\nFor users deploying custom OpenAI-compatible embedding servers:\n\n```bash\nOPENAI_EMBED_API_KEY=YOUR_API_KEY\nOPENAI_EMBED_BASE_URL=YOUR_CUSTOM_URL\nOPENAI_CUSTOM_EMBED=true\n```\n\n资料来源：[README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n\n## Document Processing Pipeline\n\nThe embedding process is part of a larger document ingestion pipeline:\n\n```mermaid\ngraph LR\n    A[File Upload] --> B[Reader]\n    B --> C[Text Extraction]\n    C --> D[Chunking]\n    D --> E[Chunk Processing]\n    E --> F[Embedding Generation]\n    F --> G[Vector Storage]\n    G --> H[Indexing]\n```\n\n### Step 1: Document Reading\n\nDocuments are first processed by a Reader component that extracts text content based on file type. Supported formats include PDF, DOCX, TXT, CSV, XLSX, XLS, and more.\n\n### Step 2: Chunking\n\nExtracted text is split into smaller chunks using configurable chunking strategies. The chunker can be selected and configured per document.\n\n### Step 3: Embedding Generation\n\nEach chunk is passed through the selected embedder to generate a vector representation. The embedder transforms textual content into numerical vectors in a high-dimensional space.\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n\n## RAG Configuration\n\nVerba allows per-document RAG configuration including the embedder selection:\n\n```typescript\ninterface RAGConfig {\n  \"Reader\": {\n    selected: string;\n    components: Record<string, ComponentConfig>;\n  };\n  \"Chunker\": {\n    selected: string;\n    components: Record<string, ComponentConfig>;\n  };\n  \"Embedder\": {\n    selected: string;\n    components: Record<string, ComponentConfig>;\n  };\n  \"Retriever\": {\n    selected: string;\n    components: Record<string, ComponentConfig>;\n  };\n  \"Generator\": {\n    selected: string;\n    components: Record<string, ComponentConfig>;\n  };\n}\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n\n## Vector Storage in Weaviate\n\nVerba uses Weaviate as its vector database. The embeddings are stored alongside metadata for efficient similarity search operations.\n\n### Collection Management\n\nCollections in Weaviate store documents with their associated vectors:\n\n```python\n{\n    \"name\": \"collection_name\",\n    \"count\": number_of_objects,\n    \"status\": \"vector_status\",\n    \"shards\": number_of_shards\n}\n```\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Settings/InfoView.tsx)\n\n### Document Document Structure\n\nDocuments stored with embeddings contain:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `title` | string | Document title |\n| `content` | string | Original text content |\n| `extension` | string | File extension/type |\n| `labels` | list | User-defined labels |\n| `source` | string | Source URL or reference |\n| `fileSize` | int | Size in bytes |\n| `metadata` | dict | Additional metadata |\n| `vectors` | array | Embedding vectors |\n\n资料来源：[goldenverba/components/document.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/document.py)\n\n## Dependency Management\n\nCore embedding dependencies are specified in `setup.py`:\n\n```python\ninstall_requires=[\n    \"weaviate-client==4.9.6\",\n    \"openpyxl==3.1.5\",\n    \"fastapi==0.111.1\",\n    # ... additional dependencies\n]\n```\n\n资料来源：[setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n\n## Deployment Considerations\n\n### Local Deployment\n\nWhen running Verba locally, users can select embedders that don't require API keys (such as SentenceTransformers) or configure API-based embedders with appropriate keys.\n\n### Production Deployment\n\nIn production environments:\n\n- Embedder selection may be restricted based on deployment type\n- API keys should be configured via environment variables\n- Vector storage is managed through the configured Weaviate instance\n\n## Summary\n\nVerba's embedding and vector storage system provides a flexible, provider-agnostic approach to semantic search. By supporting multiple embedding providers and integrating with Weaviate for vector storage, the system enables effective retrieval-augmented generation across various use cases. Configuration can be done per-document or at the system level, giving users fine-grained control over the RAG pipeline.\n\n---\n\n<a id='page-retrieval-system'></a>\n\n## RAG Retrieval System\n\n### 相关页面\n\n相关主题：[Embedding and Vector Storage](#page-embedding-system), [LLM Generators and Answer Generation](#page-llm-generators)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [goldenverba/components/document.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/document.py)\n- [goldenverba/components/retriever/WindowRetriever.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/retriever/WindowRetriever.py)\n- [goldenverba/components/retriever/__init__.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/retriever/__init__.py)\n- [goldenverba/verba_manager.py](https://github.com/weaviate/Verba/blob/main/goldenverba/verba_manager.py)\n- [frontend/app/components/Document/DocumentExplorer.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Document/DocumentExplorer.tsx)\n- [frontend/app/components/Document/VectorView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Document/VectorView.tsx)\n- [frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n- [frontend/app/components/Chat/ChatConfig.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatConfig.tsx)\n</details>\n\n# RAG Retrieval System\n\n## Overview\n\nThe RAG (Retrieval-Augmented Generation) Retrieval System is the core query mechanism in Verba that enables semantic search across document collections. It retrieves relevant text chunks from vectorized documents stored in Weaviate and delivers them to the Generator component for answer synthesis.\n\nIn Verba's architecture, the Retrieval System operates as a pipeline component that:\n\n1. Receives user queries from the frontend chat interface\n2. Embeds the query using the configured Embedder\n3. Performs vector similarity search in Weaviate\n4. Returns ranked chunks to the chat interface for display and generation\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx](frontend/app/components/Chat/ChatConfig.tsx)\n\n---\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n    A[User Query] --> B[Frontend ChatInterface]\n    B --> C[ChatConfig - Retriever Selection]\n    C --> D[WindowRetriever]\n    D --> E[Weaviate Vector Database]\n    D --> F[Embedder Service]\n    F --> E\n    E --> G[Retrieved Chunks]\n    G --> B\n    G --> H[Generator - Answer Synthesis]\n```\n\n### Component Pipeline\n\nThe RAG pipeline in Verba follows a modular architecture where each component can be swapped via configuration:\n\n| Component | Role | Location |\n|-----------|------|----------|\n| **Embedder** | Converts query text to vector embedding | `goldenverba/components/embedder/` |\n| **Retriever** | Performs similarity search | `goldenverba/components/retriever/` |\n| **Generator** | Synthesizes answer from retrieved chunks | `goldenverba/components/generator/` |\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:35-48](frontend/app/components/Chat/ChatConfig.tsx)\n\n---\n\n## Retriever Components\n\n### WindowRetriever\n\nThe `WindowRetriever` is the primary retriever implementation that performs vector similarity search with configurable parameters.\n\n**File:** `goldenverba/components/retriever/WindowRetriever.py`\n\n**Configuration Options:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `window_distance` | int | 3 | Number of chunks to include around the matched chunk |\n| `max_chunks` | int | 10 | Maximum number of chunks to retrieve per query |\n| `min_score` | float | 0.0 | Minimum similarity score threshold |\n\n### Retriever Base Class\n\nAll retrievers inherit from the base `Retriever` class which defines the standard interface:\n\n```python\nclass Retriever:\n    def __init__(self, config: Config, embedder: Embedder):\n        \"\"\"Initialize retriever with config and embedder.\"\"\"\n        \n    def retrieve(self, query: str, limit: int = 10) -> list[Chunk]:\n        \"\"\"Retrieve relevant chunks for a query.\"\"\"\n        \n    def get_name(self) -> str:\n        \"\"\"Return the retriever name.\"\"\"\n```\n\n资料来源：[goldenverba/components/retriever/__init__.py](goldenverba/components/retriever/__init__.py)\n\n---\n\n## Data Models\n\n### Document Structure\n\nDocuments are the primary data unit in Verba's retrieval system:\n\n```python\nclass Document:\n    title: str\n    content: str\n    extension: str\n    labels: list[str]\n    source: str\n    fileSize: str\n    metadata: str\n    meta: dict\n```\n\n资料来源：[goldenverba/components/document.py:1-30](goldenverba/components/document.py)\n\n### Document Creation\n\nDocuments are created from file content using `FileConfig`:\n\n```python\ndef create_document(content: str, fileConfig: FileConfig) -> Document:\n    return Document(\n        title=fileConfig.filename,\n        content=content,\n        extension=fileConfig.extension,\n        labels=fileConfig.labels,\n        source=fileConfig.source,\n        fileSize=fileConfig.file_size,\n        metadata=fileConfig.metadata,\n        meta={},\n    )\n```\n\n资料来源：[goldenverba/components/document.py:32-45](goldenverba/components/document.py)\n\n---\n\n## Frontend Integration\n\n### Document Explorer\n\nThe `DocumentExplorer` component provides a UI for browsing and searching documents:\n\n**Features:**\n- Document search with filtering by labels\n- Metadata display (file size, source URL, labels)\n- Vector visualization access\n- Document deletion functionality\n\n**File:** `frontend/app/components/Document/DocumentExplorer.tsx`\n\n```tsx\ninterface Document {\n  id: string;\n  title: string;\n  content: string;\n  fileSize: string;\n  source: string;\n  labels: string[];\n  vectors: Vector[];\n}\n```\n\n### Vector View\n\nThe `VectorView` component visualizes document vectors in the Weaviate database:\n\n```tsx\ninterface VectorData {\n  collection_name: string;\n  vectors: Vector[];\n}\n```\n\n资料来源：[frontend/app/components/Document/VectorView.tsx](frontend/app/components/Document/VectorView.tsx)\n\n---\n\n## Query Flow\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Frontend\n    participant ChatInterface\n    participant Retriever\n    participant Weaviate\n    participant Generator\n\n    User->>Frontend: Enter query\n    Frontend->>ChatInterface: Send message\n    ChatInterface->>Retriever: retrieve(query)\n    Retriever->>Retriever: embed_query(query)\n    Retriever->>Weaviate: nearVector search\n    Weaviate->>Retriever: ranked chunks\n    Retriever->>ChatInterface: return chunks\n    ChatInterface->>Frontend: display chunks\n    ChatInterface->>Generator: generate(chunks, query)\n    Generator->>User: response\n```\n\n---\n\n## Configuration\n\n### Retriever Selection in Chat Config\n\nThe Chat Config UI allows users to select and configure retrievers:\n\n```tsx\n<ComponentView\n    RAGConfig={RAGConfig}\n    component_name=\"Retriever\"\n    selectComponent={selectComponent}\n    updateConfig={updateConfig}\n    saveComponentConfig={saveComponentConfig}\n    blocked={production == \"Demo\"}\n/>\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:40-46](frontend/app/components/Chat/ChatConfig.tsx)\n\n### Production Modes\n\n| Mode | Retrieval | Description |\n|------|-----------|-------------|\n| `Demo` | Disabled | Read-only demo with pre-loaded data |\n| `Local` | Full Access | Local Weaviate + Ollama setup |\n| `Production` | Full Access | External Weaviate Cloud |\n\n---\n\n## Verba Manager Integration\n\nThe `VerbaManager` orchestrates all RAG components including retrieval:\n\n**Key Responsibilities:**\n- Initialize and manage component lifecycle\n- Route queries through the RAG pipeline\n- Manage Weaviate connections\n- Handle configuration persistence\n\n资料来源：[goldenverba/verba_manager.py](goldenverba/verba_manager.py)\n\n---\n\n## Summary\n\nThe RAG Retrieval System in Verba provides a flexible, modular mechanism for semantic search across vectorized documents:\n\n| Aspect | Implementation |\n|--------|----------------|\n| **Retrieval Method** | Vector similarity search via Weaviate |\n| **Primary Retriever** | WindowRetriever with configurable window distance |\n| **Query Flow** | Embed → Search → Rank → Return |\n| **Frontend Access** | ChatInterface with chunk display |\n| **Configuration** | Per-deployment RAGConfig with swap-able components |\n\nThis architecture allows users to customize each stage of the retrieval pipeline according to their specific use case requirements.\n\n---\n\n<a id='page-llm-generators'></a>\n\n## LLM Generators and Answer Generation\n\n### 相关页面\n\n相关主题：[LLM Generators and Answer Generation](#page-llm-generators), [RAG Retrieval System](#page-retrieval-system)\n\n<details>\n<summary>Related Source Files</summary>\n\n以下源码文件用于生成本页说明：\n\n- [goldenverba/components/generation/OpenAIGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/OpenAIGenerator.py)\n- [goldenverba/components/generation/AnthrophicGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/AnthrophicGenerator.py)\n- [goldenverba/components/generation/CohereGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/CohereGenerator.py)\n- [goldenverba/components/generation/GroqGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/GroqGenerator.py)\n- [goldenverba/components/generation/OllamaGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/OllamaGenerator.py)\n- [goldenverba/components/generation/GeminiGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/GeminiGenerator.py)\n- [goldenverba/components/generation/NovitaGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/NovitaGenerator.py)\n- [goldenverba/components/generation/UpstageGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/UpstageGenerator.py)\n- [goldenverba/components/generation/AtlasCloudGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/AtlasCloudGenerator.py)\n</details>\n\n# LLM Generators and Answer Generation\n\n## Overview\n\nVerba implements a modular LLM Generator system that provides answer generation capabilities for the RAG (Retrieval-Augmented Generation) pipeline. The system supports multiple LLM providers through a common interface abstraction, allowing users to choose their preferred generation backend while maintaining consistent behavior across the application.\n\nThe generation module is part of Verba's component architecture, where each generator implements a common interface that defines methods for retrieving supported models, generating responses, and managing authentication credentials.\n\n## Architecture\n\n### Generator Interface\n\nAll LLM generators in Verba inherit from a common base class that defines the contract for generation operations. This design enables:\n\n- **Provider Agnosticism**: Switch between LLM providers without changing application code\n- **Consistent API**: All generators expose the same methods for model listing and text generation\n- **Credential Management**: Unified handling of API keys and authentication\n\n### Supported Providers\n\nVerba supports the following LLM providers for answer generation:\n\n| Provider | Class Name | API Type | Cloud/Local |\n|----------|------------|----------|-------------|\n| OpenAI | `OpenAIGenerator` | REST API | Cloud |\n| Anthropic | `AnthrophicGenerator` | REST API | Cloud |\n| Cohere | `CohereGenerator` | REST API | Cloud |\n| Groq | `GroqGenerator` | REST API | Cloud |\n| Ollama | `OllamaGenerator` | Local API | Local |\n| Gemini | `GeminiGenerator` | REST API | Cloud |\n| Novita AI | `NovitaGenerator` | REST API | Cloud |\n| Upstage | `UpstageGenerator` | REST API | Cloud |\n| Atlas Cloud | `AtlasCloudGenerator` | REST API | Cloud |\n\n## Generation Workflow\n\n```mermaid\ngraph TD\n    A[User Query] --> B[RAG Pipeline]\n    B --> C[Retrieval: Find Relevant Chunks]\n    C --> D[Context Assembly]\n    D --> E[LLM Generator]\n    E --> F[Prompt Construction]\n    F --> G[API Call to LLM Provider]\n    G --> H[Response Parsing]\n    H --> I[Formatted Answer]\n    \n    J[Credentials] --> E\n    K[System Prompt] --> F\n    L[Model Selection] --> G\n```\n\n## Configuration\n\n### Environment Variables\n\nGeneration behavior can be configured through environment variables:\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `OLLAMA_MODEL` | Default Ollama model for local generation | For Ollama setup |\n| `OLLAMA_EMBED_MODEL` | Default Ollama embedding model | For Ollama setup |\n| `OPENAI_API_KEY` | API key for OpenAI provider | For OpenAI setup |\n| `ANTHROPIC_API_KEY` | API key for Anthropic/Claude | For Anthropic setup |\n\n### Runtime Configuration\n\nThe frontend allows dynamic model selection through the `ChatConfig` component. When users select a deployment type, Verba fetches available models from the configured provider and presents them in the UI.\n\nFrom `frontend/app/components/Chat/ChatInterface.tsx`:\n```typescript\n<ChatConfig\n  addStatusMessage={addStatusMessage}\n  production={production}\n  RAGConfig={RAGConfig}\n  credentials={credentials}\n  setRAGConfig={setRAGConfig}\n  onReset={onResetConfig}\n  onSave={onSaveConfig}\n/>\n```\n\n## Component Interaction\n\n### Chat Pipeline\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Frontend\n    participant Backend\n    participant Generator\n    participant LLM_Provider\n    \n    User->>Frontend: Submit Query\n    Frontend->>Backend: /api/chat with query\n    Backend->>Generator: Generate response\n    Generator->>LLM_Provider: API request\n    LLM_Provider-->>Generator: LLM Response\n    Generator-->>Backend: Formatted answer\n    Backend-->>Frontend: Stream response\n    Frontend->>User: Display answer\n```\n\n### Message Handling\n\nThe chat interface manages different fetching states during generation:\n\n```typescript\n{fetchingStatus === \"CHUNKS\" && \"Retrieving...\"}\n{fetchingStatus === \"RESPONSE\" && \"Generating...\"}\n```\n\nUsers can cancel ongoing generation through the UI, which sets the fetching status to `DONE` and stops further API calls.\n\n## Document-to-Answer Flow\n\nWhen processing documents for RAG:\n\n1. **Ingestion**: Documents are parsed and chunked via Reader components\n2. **Storage**: Chunks are embedded and stored in Weaviate\n3. **Retrieval**: Relevant chunks are fetched based on query similarity\n4. **Generation**: Selected chunks are sent to the LLM generator with the user's query\n\nFrom `goldenverba/components/document.py`:\n```python\ndef create_document(content: str, fileConfig: FileConfig) -> Document:\n    \"\"\"Create a Document object from the file content.\"\"\"\n    return Document(\n        title=fileConfig.filename,\n        content=content,\n        extension=fileConfig.extension,\n        labels=fileConfig.labels,\n        source=fileConfig.source,\n        fileSize=fileConfig.file_size,\n        metadata=fileConfig.metadata,\n        meta={},\n    )\n```\n\n## Deployment Types\n\nVerba supports different deployment configurations that affect generation behavior:\n\n| Deployment | Description | Generator Usage |\n|------------|-------------|-----------------|\n| Weaviate Cloud | Full cloud deployment | Cloud-based LLM APIs |\n| Docker | Containerized deployment | Configurable via environment |\n| Local | Development setup | Often uses Ollama |\n| Custom | User-defined infrastructure | Flexible configuration |\n\nThe deployment type is selected during the initial setup through the `LoginView` component:\n\nFrom `frontend/app/components/Login/LoginView.tsx`:\n```typescript\n{production == \"Local\" && (\n    <div className=\"flex flex-col justify-start gap-2 w-full\">\n        <VerbaButton\n            Icon={FaDatabase}\n            title=\"Weaviate\"\n            onClick={() => setSelectedDeployment(\"Weaviate\")}\n        />\n        {/* Docker, Custom, Local options */}\n    </div>\n)}\n```\n\n## Model Selection\n\n### Dynamic Model Retrieval\n\nVerba supports dynamic model name retrieval for OpenAI-compatible APIs based on the provided API key and URL. This allows the system to automatically discover and list available models from the configured provider.\n\nFrom `CHANGELOG.md`:\n> Dynamic model name retrieval for OpenAI Generator based on OpenAI URL and API Key\n\n### Model Fallback\n\nWhen automatic model detection is unavailable, Verba uses default models:\n- **OpenAI**: `gpt-4o-mini`\n- **Anthropic**: `claude-3-haiku-20240307`\n- **Ollama**: Configurable via `OLLAMA_MODEL`\n\n## Status and Error Handling\n\nThe application uses a status messenger system to communicate generation states to users:\n\n```typescript\n{messages.filter((message) => {\n    const messageTime = new Date(message.timestamp).getTime();\n    const currentTime = new Date().getTime();\n    return currentTime - messageTime < 5000; // 5 seconds\n}).map((message, index) => (\n    <motion.div key={index}>\n        {/* Status message display */}\n    </motion.div>\n))}\n```\n\nMessages are categorized by type and automatically expire after 5 seconds.\n\n## Reset Capabilities\n\nThe Settings panel (`InfoView`) provides reset functionality that affects generation:\n\n| Action | Scope | Effect on Generation |\n|--------|-------|----------------------|\n| Reset Documents | Data | Clears chunks, requires re-retrieval |\n| Reset Config | Configuration | Resets model selection and prompts |\n| Reset Verba | All Data | Full system reset including models |\n| Reset Suggestions | Autocomplete | Clears cached suggestions |\n\nFrom `frontend/app/components/Settings/InfoView.tsx`:\n```typescript\n<UserModalComponent\n    modal_id=\"reset-documents\"\n    title=\"Reset Documents\"\n    text=\"Are you sure you want to reset all documents?\"\n    triggerAccept={resetDocuments}\n    triggerString=\"Reset\"\n/>\n```\n\n## Dependencies\n\nThe generation module relies on the following core dependencies:\n\nFrom `setup.py`:\n```python\ninstall_requires=[\n    \"weaviate-client==4.9.6\",\n    \"fastapi==0.111.1\",\n    \"uvicorn[standard]==0.29.0\",\n    \"click==8.1.7\",\n    # Provider-specific SDKs loaded dynamically\n]\n```\n\n## Version History\n\n| Version | Changes |\n|---------|---------|\n| 2.1.3 | Added `OLLAMA_MODEL` and `OLLAMA_EMBED_MODEL` environment variables |\n| 2.1.2 | Added Novita Generator |\n| 2.1.1 | Dynamic model retrieval for OpenAI Generator |\n| 2.1.0 | Added Upstage Generator, Groq, improved configuration |\n\n## Best Practices\n\n1. **API Key Security**: Store API keys in `.env` files rather than hardcoding\n2. **Model Selection**: Choose models based on task requirements (speed vs. quality)\n3. **Chunk Configuration**: Adjust chunk sizes to match model's context window\n4. **Rate Limits**: Be aware of provider-specific rate limits for high-volume usage\n\n## See Also\n\n- [Retrieval System](docs/retrieval.md)\n- [Embedders and Vectorization](docs/embedders.md)\n- [Document Ingestion Pipeline](docs/ingestion.md)\n- [Deployment Guide](docs/deployment.md)\n\n---\n\n<a id='page-embedders'></a>\n\n## Embedder Configuration\n\n### 相关页面\n\n相关主题：[Embedding and Vector Storage](#page-embedding-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n- [frontend/app/components/Chat/ChatConfig.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatConfig.tsx)\n- [frontend/app/components/Ingestion/ComponentView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/ComponentView.tsx)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n</details>\n\n# Embedder Configuration\n\n## Overview\n\nThe Embedder is a core component in Verba's RAG (Retrieval-Augmented Generation) pipeline responsible for converting text content into vector embeddings. These embeddings enable semantic search capabilities by representing documents and queries as numerical vectors in a high-dimensional space.\n\nVerba supports multiple embedder implementations including OpenAI, Ollama, Upstage, and other providers. The embedder configuration system allows users to select their preferred embedding provider, configure provider-specific settings, and integrate with the broader RAG pipeline.\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:24-35]()\n\n## Architecture\n\n### RAG Pipeline Integration\n\nThe Embedder operates as part of a modular RAG configuration system alongside the Retriever and Generator components.\n\n```mermaid\ngraph TD\n    A[Document Input] --> B[Reader]\n    B --> C[Chunker]\n    C --> D[Embedder]\n    D --> E[Weaviate Vector Store]\n    F[User Query] --> G[Embedder]\n    G --> H[Retriever]\n    H --> I[Generator]\n    I --> J[Response]\n    E -.-> H\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:24-35]()\n\n### Component Selection Flow\n\nUsers interact with the embedder configuration through a component selection interface:\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant ComponentView\n    participant RAGConfig\n    participant Embedder\n    \n    User->>ComponentView: Select Embedder Component\n    ComponentView->>RAGConfig: updateConfig(Embedder, selection)\n    RAGConfig->>Embedder: Apply Configuration\n    Embedder-->>RAGConfig: Confirm Settings\n    RAGConfig-->>ComponentView: Update UI\n    ComponentView-->>User: Display Updated State\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-100]()\n\n## Configuration UI\n\n### Embedder Selection Panel\n\nThe embedder can be configured through the ingestion interface where users select and customize embedding models for their documents.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `selected` | string | Currently selected embedder name |\n| `components` | object | Available embedder implementations |\n| `description` | string | Human-readable description of selected embedder |\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:85-95]()\n\n### Display and Configuration\n\nThe UI displays the currently selected embedder with its configuration:\n\n```tsx\n<div className=\"flex gap-2 justify-between items-center text-text-verba\">\n  <p className=\"flex min-w-[8vw]\">Embedder</p>\n  <label className=\"input flex items-center gap-2 w-full bg-bg-verba\">\n    <input\n      type=\"text\"\n      className=\"grow w-full\"\n      value={fileMap[selectedFileData].rag_config[\"Embedder\"].selected}\n      disabled={true}\n    />\n  </label>\n</div>\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:85-95]()\n\n### Dynamic Description\n\nEach embedder component provides a description that is displayed in the UI:\n\n```tsx\n<div className=\"flex gap-2 items-center text-text-verba\">\n  <p className=\"flex min-w-[8vw]\"></p>\n  <p className=\"text-sm text-text-alt-verba text-start\">\n    {selectedFileData &&\n      fileMap[selectedFileData].rag_config[\"Embedder\"].components[\n        fileMap[selectedFileData].rag_config[\"Embedder\"].selected\n      ].description}\n  </p>\n</div>\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:97-106]()\n\n## RAG Configuration System\n\n### Configuration Structure\n\nThe embedder is configured within the `RAGConfig` object which manages all pipeline components:\n\n```typescript\ninterface RAGConfig {\n  Embedder: {\n    selected: string;\n    components: Record<string, EmbedderComponent>;\n  };\n  Generator: {\n    selected: string;\n    components: Record<string, GeneratorComponent>;\n  };\n  Retriever: {\n    selected: string;\n    components: Record<string, RetrieverComponent>;\n  };\n}\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:1-50]()\n\n### Component View Integration\n\nThe `ComponentView` component renders the embedder selection UI:\n\n```tsx\n<ComponentView\n  RAGConfig={RAGConfig}\n  component_name=\"Embedder\"\n  selectComponent={selectComponent}\n  updateConfig={updateConfig}\n  saveComponentConfig={saveComponentConfig}\n  blocked={production == \"Demo\"}\n/>\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:24-35]()\n\n## Supported Embedder Providers\n\n### Provider Matrix\n\n| Provider | Environment Variables | Version Added | Features |\n|----------|----------------------|---------------|----------|\n| OpenAI | `OPENAI_API_KEY`, `OPENAI_URL` | Base | Dynamic model name retrieval |\n| Ollama | `OLLAMA_EMBED_MODEL` | 2.1.3 | Local embedding models |\n| Upstage | (Upstage-specific) | 2.1.0 | High-performance embeddings |\n\n资料来源：[CHANGELOG.md:1-30](), [setup.py:1-50]()\n\n### Environment Variables\n\nVerba supports environment variables for embedder configuration:\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `OLLAMA_EMBED_MODEL` | Ollama embedding model name | `nomic-embed-text` |\n| `OPENAI_API_KEY` | OpenAI API key | `sk-...` |\n| `OPENAI_URL` | OpenAI API endpoint | `https://api.openai.com/v1` |\n\n资料来源：[CHANGELOG.md:1-15]()\n\n## Deployment Modes\n\n### Demo Mode Restrictions\n\nIn Demo mode, the embedder configuration is locked to prevent changes:\n\n```tsx\nblocked={production == \"Demo\"}\n```\n\nThis ensures that demo deployments maintain consistent behavior and don't allow users to modify the embedding pipeline.\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:24-35]()\n\n### Configuration Persistence\n\nThe embedder configuration is saved through the `saveComponentConfig` callback:\n\n```tsx\n<ComponentView\n  RAGConfig={RAGConfig}\n  component_name=\"Embedder\"\n  selectComponent={selectComponent}\n  updateConfig={updateConfig}\n  saveComponentConfig={saveComponentConfig}\n  blocked={production == \"Demo\"}\n/>\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:24-35]()\n\n## Debugging Embedder Configuration\n\n### Debug Modal\n\nVerba provides a debug view for inspecting file configuration including embedder settings:\n\n```tsx\n<VerbaButton\n  Icon={CgDebug}\n  onClick={openDebugModal}\n  className=\"max-w-min\"\n/>\n\n<dialog id={\"File_Debug_Modal\"} className=\"modal\">\n  <pre className=\"whitespace-pre-wrap text-xs\">\n    {selectedFileData\n      ? (() => {\n          const objCopy = { ...fileMap[selectedFileData] };\n          objCopy.content = \"File Content\";\n          return JSON.stringify(objCopy, null, 2);\n        })()\n      : \"\"}\n  </pre>\n</dialog>\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:110-130]()\n\n## File-Level Configuration\n\n### Per-File Embedder Override\n\nEach file can have its own embedder configuration that overrides the global RAG config:\n\n```typescript\ninterface FileConfig {\n  filename: string;\n  extension: string;\n  labels: string[];\n  source: string;\n  file_size: number;\n  metadata: Record<string, any>;\n  rag_config: RAGConfig;\n}\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-100]()\n\n### Accessing File Embedder Config\n\n```typescript\nfileMap[selectedFileData].rag_config[\"Embedder\"].selected\nfileMap[selectedFileData].rag_config[\"Embedder\"].components\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:85-106]()\n\n## Version History\n\n| Version | Changes |\n|---------|---------|\n| 2.1.3 | Added `OLLAMA_MODEL` and `OLLAMA_EMBED_MODEL` environment variables |\n| 2.1.0 | Added Upstage Embedder support |\n| 2.1.1 | Dynamic model name retrieval for OpenAI |\n\n资料来源：[CHANGELOG.md:1-30]()\n\n## Dependencies\n\nVerba requires the Weaviate client for vector storage operations:\n\n```python\ninstall_requires=[\n    \"weaviate-client==4.9.6\",\n    \"python-dotenv==1.0.0\",\n    \"openpyxl==3.1.5\",\n    \"wasabi==1.1.2\",\n    \"fastapi==0.111.1\",\n    \"uvicorn[standard]==0.29.0\",\n    \"gunicorn==22.0.0\",\n    \"click==8.1.7\",\n]\n```\n\n资料来源：[setup.py:15-25]()\n\n## Best Practices\n\n1. **Use Environment Variables**: Store API keys and model names in `.env` files rather than hardcoding\n2. **Test in Non-Demo Mode**: Full configuration features require non-Demo deployment\n3. **Leverage Debug Mode**: Use the debug modal to inspect configuration state\n4. **Check Provider Support**: Ensure your chosen embedder provider is compatible with your deployment mode\n\n---\n\n<a id='page-frontend-components'></a>\n\n## Frontend Component Overview\n\n<details>\n<summary>Related Source Files</summary>\n\nThe following source files were used to generate this documentation:\n\n- [frontend/app/page.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/page.tsx)\n- [frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n- [frontend/app/components/Chat/ChatMessage.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatMessage.tsx)\n- [frontend/app/components/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n- [frontend/app/components/Navigation/StatusMessenger.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/StatusMessenger.tsx)\n- [frontend/app/components/Document/ContentView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Document/ContentView.tsx)\n- [frontend/app/components/Settings/InfoView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Settings/InfoView.tsx)\n- [frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n- [frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n- [frontend/app/components/Ingestion/FileSelectionView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/FileSelectionView.tsx)\n</details>\n\n# Frontend Component Overview\n\n## Introduction\n\nThe Verba frontend is a React-based web application that provides a user-friendly interface for Retrieval-Augmented Generation (RAG) operations. Built with Next.js and TypeScript, the frontend enables users to interact with their data through chat interfaces, document management, and configuration settings.\n\n资料来源：[frontend/app/page.tsx:1-50]()\n\n## Architecture Overview\n\nThe frontend follows a modular component-based architecture organized by functionality. The application uses WebSocket connections for real-time communication with the backend server, enabling live status updates and streaming responses.\n\n```mermaid\ngraph TD\n    A[App Entry Point] --> B[LoginView]\n    A --> C[Main Application]\n    C --> D[NavbarComponent]\n    C --> E[ChatInterface]\n    C --> F[Document Components]\n    C --> G[Ingestion Components]\n    C --> H[Settings Components]\n    D --> I[StatusMessenger]\n    E --> J[ChatMessage]\n    E --> K[ChatConfig]\n```\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:1-100]()\n\n## Core Components\n\n### Navigation Components\n\n#### NavbarComponent\n\nThe navigation bar serves as the primary routing mechanism within the application. It displays different pages based on the user's current selection and deployment mode.\n\n| Prop | Type | Description |\n|------|------|-------------|\n| `currentPage` | `string` | Current active page identifier |\n| `setCurrentPage` | `function` | Callback to change active page |\n| `production` | `string` | Deployment type (Local, Demo, Docker, etc.) |\n| `gitHubStars` | `string` | GitHub star count display |\n\nThe NavbarComponent conditionally renders menu items based on the `production` environment. In non-Demo modes, additional options like \"Import Data\" and \"Settings\" become available.\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:1-150]()\n\n#### StatusMessengerComponent\n\nThe StatusMessengerComponent provides toast-style notifications for application events. Messages are filtered to display only those within the last 5 seconds, providing transient user feedback.\n\n```mermaid\ngraph LR\n    A[Message Event] --> B[Timestamp Check]\n    B --> C{Within 5s?}\n    C -->|Yes| D[Animate In]\n    C -->|No| E[Filter Out]\n    D --> F[Display Message]\n    F --> G[Animate Out]\n```\n\nMessages are color-coded by type using a `getMessageColor()` function and include icons for visual identification.\n\n资料来源：[frontend/app/components/Navigation/StatusMessenger.tsx:1-80]()\n\n### Chat Components\n\n#### ChatInterface\n\nThe ChatInterface is the central component for RAG interactions. It manages chat messages, user input, and the configuration panel.\n\n| State Variable | Type | Purpose |\n|---------------|------|---------|\n| `messages` | `Message[]` | Array of chat messages |\n| `previewText` | `string` | Streaming response preview |\n| `isFetching` | `RefObject` | Fetching status indicator |\n| `selectedSetting` | `string` | Active sub-panel (Chat/Config) |\n| `fetchingStatus` | `string` | Current operation status |\n\nThe component supports two sub-views: the chat view for conversation and a configuration view for RAG settings. A cancel button allows users to interrupt ongoing operations.\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:1-150]()\n\n#### ChatMessage\n\nThe ChatMessage component renders individual messages with support for multiple message types and syntax highlighting for code blocks.\n\n| Message Type | Styling | Features |\n|-------------|---------|----------|\n| `user` | Right-aligned, primary background | Plain text display |\n| `system` | Left-aligned, alternate background | Markdown + syntax highlighting |\n| `error` | Warning background color | Error notifications |\n| `retrieval` | Standard background | Retrieval results |\n\nFor system messages containing code, the component uses `react-syntax-highlighter` with theme support for both light and dark modes.\n\n```tsx\n<SyntaxHighlighter\n  style={selectedTheme.theme === \"dark\" ? oneDark : oneLight}\n  language={match[1]}\n  PreTag=\"div\"\n>\n  {String(children).replace(/\\n$/, \"\")}\n</SyntaxHighlighter>\n```\n\n资料来源：[frontend/app/components/Chat/ChatMessage.tsx:1-100]()\n\n### Document Components\n\n#### ContentView\n\nThe ContentView component displays document content with pagination support for both chunks and pages.\n\n| Feature | Description |\n|---------|-------------|\n| Chunk Navigation | Previous/Next chunk buttons |\n| Page Navigation | Page-based content display |\n| Scroll Handling | Overflow auto-scroll for long content |\n| Label Display | Truncated label badges with max-width constraints |\n\nThe component conditionally renders navigation text based on whether chunk scores are available, switching between \"Chunk\" and \"Page\" labels.\n\n资料来源：[frontend/app/components/Document/ContentView.tsx:1-100]()\n\n### Ingestion Components\n\n#### BasicSettingView\n\nThe BasicSettingView provides configuration options for document ingestion, including source links and labels.\n\n| Field | Purpose | Constraints |\n|-------|---------|-------------|\n| `source` | Reference link to original document | Optional field |\n| `label` | Document categorization labels | Enter key adds label |\n| `chunker` | Text chunking strategy | Read-only display |\n| `embedder` | Embedding model selection | Read-only display |\n\nLabels are added via keyboard (Enter key) or button click, with each label rendered as a removable badge.\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-150]()\n\n#### FileSelectionView\n\nThe FileSelectionView displays a list of selected files and provides import functionality.\n\nFiles are rendered as `FileComponent` instances, each with delete and selection capabilities. The import footer contains action buttons that become available when the WebSocket connection is online.\n\n```mermaid\ngraph TD\n    A[FileSelectionView] --> B[FileComponent List]\n    B --> C{User Action}\n    C --> D[Delete File]\n    C --> E[Select File]\n    C --> F[Import Selected]\n    F --> G{WebSocket Online?}\n    G -->|Yes| H[Show Import Button]\n    G -->|No| I[Hide Import Button]\n```\n\n资料来源：[frontend/app/components/Ingestion/FileSelectionView.tsx:1-100]()\n\n### Settings Components\n\n#### InfoView\n\nThe InfoView component displays system information and provides reset functionality for various aspects of the application.\n\n| Section | Information Displayed |\n|---------|----------------------|\n| Weaviate Cluster | Name, status, shard count |\n| Collections | Collection count, names, object counts |\n| Reset Options | Documents, Config, Verba, Suggestions |\n\nReset operations are protected by modal confirmations using the `UserModalComponent`, requiring explicit user confirmation before executing destructive actions.\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:1-100]()\n\n### Login Components\n\n#### LoginView\n\nThe LoginView handles initial deployment type selection for the application.\n\n| Deployment Option | Icon | Description |\n|------------------|------|-------------|\n| Weaviate | `FaDatabase` | Weaviate Cloud deployment |\n| Docker | `FaDocker` | Docker container deployment |\n| Custom | `TbDatabaseEdit` | Custom backend connection |\n| Local | `FaLaptopCode` | Local development mode |\n\nThe component manages connection states and displays loading indicators during authentication attempts.\n\n资料来源：[frontend/app/components/Login/LoginView.tsx:1-100]()\n\n## Application Entry Point\n\nThe main page component (`frontend/app/page.tsx`) orchestrates the overall application flow, handling:\n\n- Environment detection and configuration\n- WebSocket connection management\n- Theme persistence\n- Page routing based on deployment status\n\n```mermaid\ngraph TD\n    A[Page Load] --> B{Production Mode?}\n    B -->|Demo| C[Direct to Main]\n    B -->|Local| D[LoginView]\n    D --> E{Deployment Selected}\n    E -->|Weaviate| F[Configure Weaviate]\n    E -->|Docker| G[Connect to Docker]\n    E -->|Custom| H[Configure Custom]\n    E -->|Local| I[Full Setup]\n    F --> J[Main Application]\n    G --> J\n    H --> J\n    I --> J\n    C --> J\n```\n\nThe footer displays a \"Built with ♥ and Weaviate\" message, confirming the project's association with Weaviate.\n\n资料来源：[frontend/app/page.tsx:1-80]()\n\n## Theme System\n\nThe application supports both light and dark themes, with theme preferences persisted across sessions. Theme values are passed down to components that require styling adjustments, such as `ChatMessage` for syntax highlighting.\n\n```tsx\n// Theme-dependent syntax highlighting\nconst codeStyle = selectedTheme.theme === \"dark\" ? oneDark : oneLight;\n```\n\n## Component Communication\n\nComponents communicate through several mechanisms:\n\n1. **Props Drilling**: Parent components pass state and callbacks to children via props\n2. **Ref Objects**: Used for mutable values that don't trigger re-renders (e.g., `isFetching`)\n3. **WebSocket Events**: Real-time updates from the backend server\n4. **State Callbacks**: Functions like `setCurrentPage` for navigation state\n\n## State Management Summary\n\n| Component Area | Primary State | Secondary State |\n|---------------|---------------|-----------------|\n| Chat | `messages`, `previewText` | `fetchingStatus`, `selectedSetting` |\n| Documents | `content`, `chunkScores` | `page`, `selectedDocument` |\n| Ingestion | `fileMap`, `selectedFileData` | `source`, `label` |\n| Navigation | `currentPage` | `socketOnline`, `production` |\n| Settings | `collectionPayload` | `clusterPayload`, `credentials` |\n\n## Styling Conventions\n\nThe frontend uses Tailwind CSS with custom color variables following the `-verba` suffix convention:\n\n| Color Variable | Usage |\n|---------------|-------|\n| `bg-bg-verba` | Primary background |\n| `bg-bg-alt-verba` | Alternate background |\n| `text-text-verba` | Primary text |\n| `text-text-alt-verba` | Alternate text |\n| `bg-button-verba` | Button backgrounds |\n| `hover:bg-button-hover-verba` | Button hover states |\n\nThis systematic naming ensures consistent theming throughout the application.\n\n## Key Features Summary\n\n| Feature | Components | Description |\n|---------|------------|-------------|\n| Chat Interface | ChatInterface, ChatMessage | RAG conversation with syntax highlighting |\n| Document Explorer | ContentView, DocumentExplorer | View and navigate documents/chunks |\n| Data Import | FileSelectionView, BasicSettingView | File upload and configuration |\n| System Settings | InfoView, SettingsView | System info and reset options |\n| Real-time Updates | StatusMessenger | Toast notifications for events |\n| Navigation | NavbarComponent | Page routing and menu |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：weaviate/Verba\n\n摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：1.0.1 Beautiful Verba。\n\n## 1. 安装坑 · 来源证据：1.0.1 Beautiful Verba\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.0.1 Beautiful Verba\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b08b22b1d7404da6ae9d8153c53602cd | https://github.com/weaviate/Verba/releases/tag/1.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：v0.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.4.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_199393ab54bc4fd79d576c42dc3198f2 | https://github.com/weaviate/Verba/releases/tag/0.4.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v1.0.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_90c577983a844f3ba246a181a8e03997 | https://github.com/weaviate/Verba/releases/tag/v1.0.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：v2.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0ec01ecbe8494b08a039e08f6bf68f01 | https://github.com/weaviate/Verba/releases/tag/v2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:672002598 | https://github.com/weaviate/Verba | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | last_activity_observed missing\n\n## 7. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:672002598 | https://github.com/weaviate/Verba | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:672002598 | https://github.com/weaviate/Verba | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:672002598 | https://github.com/weaviate/Verba | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 来源证据：v0.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.3.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_29616574b8474fb7a44c6d3350b062fd | https://github.com/weaviate/Verba/releases/tag/0.3.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 安全/权限坑 · 来源证据：v0.3.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.3.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8c5e79dc1cf3480b9792cbd54643bb14 | https://github.com/weaviate/Verba/releases/tag/0.3.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 安全/权限坑 · 来源证据：v2.1.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.2\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9dc754c525ec48808ee74f66f9694312 | https://github.com/weaviate/Verba/releases/tag/v2.1.2 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 13. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | issue_or_pr_quality=unknown\n\n## 14. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | release_recency=unknown\n\n<!-- canonical_name: weaviate/Verba; human_manual_source: deepwiki_human_wiki -->\n",
      "markdown_key": "verba",
      "pages": "draft",
      "source_refs": [
        {
          "evidence_id": "github_repo:672002598",
          "kind": "repo",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/weaviate/Verba"
        },
        {
          "evidence_id": "art_a3c9705650364eeebc7db1ce7b3ab9aa",
          "kind": "docs",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/weaviate/Verba#readme"
        }
      ],
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "Verba 说明书",
      "toc": [
        "https://github.com/weaviate/Verba 项目说明书",
        "目录",
        "Introduction to Verba",
        "Overview",
        "Core Features",
        "Architecture Overview",
        "Deployment Options",
        "Supported Integrations",
        "Doramagic 踩坑日志"
      ]
    }
  },
  "quality_gate": {
    "blocking_gaps": [],
    "category_confidence": "medium",
    "compile_status": "ready_for_review",
    "five_assets_present": true,
    "install_sandbox_verified": true,
    "missing_evidence": [],
    "next_action": "publish to Doramagic.ai project surfaces",
    "prompt_preview_boundary_ok": true,
    "publish_status": "publishable",
    "quick_start_verified": true,
    "repo_clone_verified": true,
    "repo_commit": "6695928e1a9341086f7cf61bd5881a546c203b3c",
    "repo_inspection_error": null,
    "repo_inspection_files": [
      "Dockerfile",
      "README.md",
      "docker-compose.yml"
    ],
    "repo_inspection_verified": true,
    "review_reasons": [],
    "tag_count_ok": true,
    "unsupported_claims": []
  },
  "schema_version": "0.1",
  "user_assets": {
    "ai_context_pack": {
      "asset_id": "ai_context_pack",
      "filename": "AI_CONTEXT_PACK.md",
      "markdown": "# verba - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 verba 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install goldenverba` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0006` supported 0.86\n- `git clone https://github.com/weaviate/Verba` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0007` supported 0.86\n- `pip install -e .` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `pip install goldenverba[huggingface]` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `git clone https://github.com/weaviate/Verba.git` 证据：`README.md` Claim：`clm_0007` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、环境变量 / API Key\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0006` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `goldenverba/components/embedding/CohereEmbedder.py`, `goldenverba/components/generation/AnthrophicGenerator.py`, `goldenverba/components/generation/CohereGenerator.py` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0008` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0009` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：294\n- 重要文件覆盖：26/294\n- 证据索引条目：25\n- 角色 / Skill 条目：8\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 verba 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 verba 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 verba 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 8 个角色 / Skill / 项目文档条目。\n\n- **Verba**（project_doc）：The Golden RAGtriever - Community Edition ✨ 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Verba Contribution Guidelines**（project_doc）：Welcome to the Verba community! We're thrilled that you're interested in contributing to the Verba project. Verba is a collaborative open-source project, and we believe that everyone has something unique to contribute. Below you'll find our guidelines which aim to make contributing to Verba a respectful and pleasant experience for everyone. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Changelog**（project_doc）：All notable changes to this project will be documented in this file. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Verba - Frontend Documentation**（project_doc）：Verba's Frontend is a NextJS https://nextjs.org/ application used together with TailwindCSS https://tailwindcss.com/ and DaisyUI https://daisyui.com/ . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`FRONTEND.md`\n- **Installing Python and Setting Up a Virtual Environment**（project_doc）：Installing Python and Setting Up a Virtual Environment 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`PYTHON_TUTORIAL.md`\n- **Verba - Technical Documentation**（project_doc）：This technical documentation is intended for developers who want to understand the inner workings of Verba. Please note that this document might be uncomplete and missing some parts. If you encounter any issues or have questions, please feel free to open an issue. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`TECHNICAL.md`\n- **Verba Feature Template**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/verba-feature-template.md`\n- **Verba Issue Template**（project_doc）：- pip install goldenverba - pip install from source - Docker installation 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/verba-issue-template.md`\n\n## 证据索引\n\n- 共索引 25 条证据。\n\n- **Verba**（documentation）：The Golden RAGtriever - Community Edition ✨ 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"verba\", \"version\": \"2.1.0\", \"private\": true, \"scripts\": { \"dev\": \"next dev\", \"build\": \"next build && cp -r out/ ../goldenverba/server/frontend/out/ && rm -r out\", \"start\": \"next start -H 0.0.0.0 -p 8080\", \"lint\": \"next lint\" }, \"dependencies\": { \"@mdx-js/mdx\": \"^2.3.0\", \"@mdx-js/react\": \"^2.3.0\", \"@next/third-parties\": \"^14.2.3\", \"@react-pdf/renderer\": \"^3.4.4\", \"@react-three/drei\": \"^9.108.4\", \"@react-three/fiber\": \"^8.16.8\", \"@types/node\": \"20.5.0\", \"@types/react\": \"18.2.20\", \"@types/react-dom\": \"18.2.7\", \"@types/three\": \"^0.166.0\", \"autoprefixer\": \"10.4.15\", \"date-fns\": \"^3.6.0\", \"eslint\": \"8.47.0\", \"eslint-config-next\": \"^14.2.6\", \"framer-motion\": \"^11.3.31\", \"lil-gui\": \"^0.1… 证据：`frontend/package.json`\n- **Verba Contribution Guidelines**（documentation）：Welcome to the Verba community! We're thrilled that you're interested in contributing to the Verba project. Verba is a collaborative open-source project, and we believe that everyone has something unique to contribute. Below you'll find our guidelines which aim to make contributing to Verba a respectful and pleasant experience for everyone. 证据：`CONTRIBUTING.md`\n- **License**（source_file）：Copyright c 2020-2023, Weaviate B.V. All rights reserved. 证据：`LICENSE`\n- **Changelog**（documentation）：All notable changes to this project will be documented in this file. 证据：`CHANGELOG.md`\n- **Verba - Frontend Documentation**（documentation）：Verba's Frontend is a NextJS https://nextjs.org/ application used together with TailwindCSS https://tailwindcss.com/ and DaisyUI https://daisyui.com/ . 证据：`FRONTEND.md`\n- **Installing Python and Setting Up a Virtual Environment**（documentation）：Installing Python and Setting Up a Virtual Environment 证据：`PYTHON_TUTORIAL.md`\n- **Verba - Technical Documentation**（documentation）：This technical documentation is intended for developers who want to understand the inner workings of Verba. Please note that this document might be uncomplete and missing some parts. If you encounter any issues or have questions, please feel free to open an issue. 证据：`TECHNICAL.md`\n- **Description**（documentation）：--- name: Verba Feature Template about: Request a new feature for Verba title: \"\" labels: \"enhancement\" assignees: \"\" --- Description Additional context 证据：`.github/ISSUE_TEMPLATE/verba-feature-template.md`\n- **Description**（documentation）：- pip install goldenverba - pip install from source - Docker installation 证据：`.github/ISSUE_TEMPLATE/verba-issue-template.md`\n- **.Eslintrc**（structured_config）：{ \"extends\": \"next/core-web-vitals\" } 证据：`frontend/.eslintrc.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"downlevelIteration\": true, \"target\": \"es5\", \"lib\": \"dom\", \"dom.iterable\", \"esnext\" , \"allowJs\": true, \"skipLibCheck\": true, \"strict\": true, \"forceConsistentCasingInFileNames\": true, \"noEmit\": true, \"esModuleInterop\": true, \"module\": \"esnext\", \"moduleResolution\": \"bundler\", \"resolveJsonModule\": true, \"isolatedModules\": true, \"jsx\": \"preserve\", \"incremental\": true, \"plugins\": { \"name\": \"next\" } , \"paths\": { \"@/ \": \"./ \" } }, \"include\": \"next-env.d.ts\", \" / .ts\", \" / .tsx\", \".next/types/ / .ts\", \"../verba-rag/server/frontend/types/ / .ts\" , \"exclude\": \"node modules\" } 证据：`frontend/tsconfig.json`\n- **Dependabot**（source_file）：version: 2 updates: - package-ecosystem: pip directory: \"/\" schedule: interval: weekly day: monday open-pull-requests-limit: 10 labels: - dependencies - python 证据：`.github/dependabot.yml`\n- **.gitignore**（source_file）：.env .env pycache .DS Store .pytest cache .python-version .egg-info venv .venv venv dist build ~ .local .cache .verba .vscode verba config.json text-generation-inference test.py cache.txt .ruff cache secrets.json ollama 证据：`.gitignore`\n- **Dockerfile**（source_file）：FROM python:3.11 WORKDIR /Verba COPY . /Verba RUN pip install '.' EXPOSE 8000 CMD \"verba\", \"start\",\"--port\",\"8000\",\"--host\",\"0.0.0.0\" 证据：`Dockerfile`\n- **Manifest**（source_file）：recursive-include goldenverba/server/frontend/out 证据：`MANIFEST.in`\n- **Uncomment to use Ollama within the same docker compose**（source_file）：services: 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 - UNSTRUCTURED API KEY=$UNSTRUCTURED API KEY - UNSTRUCTURED API URL=$UNSTRUCTURED API URL - GITHUB TOKEN=$GITHUB TOKEN 证据：`docker-compose.yml`\n- **See https://help.github.com/articles/ignoring-files/ for more about ignoring files.**（source_file）：See https://help.github.com/articles/ignoring-files/ for more about ignoring files. 证据：`frontend/.gitignore`\n- **Glsl.D**（source_file）：declare module \" .glsl\" { const value: string; export default value; } 证据：`frontend/glsl.d.ts`\n- **Next.Config**（source_file）：/ @type {import 'next' .NextConfig} / const nextConfig = { output: 'export', webpack: config = { config.module.rules.push { test: /\\.glsl$/, use: 'raw-loader' , } ; return config; }, async redirects { return { source: '/v1', destination: '/', permanent: true, }, { source: '/v1/:path ', destination: '/:path ', permanent: true, }, ; }, }; 证据：`frontend/next.config.js`\n- **Postcss.Config**（source_file）：module.exports = { plugins: { tailwindcss: {}, autoprefixer: {}, }, }; 证据：`frontend/postcss.config.js`\n- **Tailwind.Config**（source_file）：import type { Config } from \"tailwindcss\"; const colors = require \"tailwindcss/colors\" ; 证据：`frontend/tailwind.config.ts`\n- **Import**（source_file）：import os import importlib import math import json from datetime import datetime 证据：`goldenverba/verba_manager.py`\n- **Pypi Commands**（source_file）：python setup.py sdist bdist wheel twine upload dist/ 证据：`pypi_commands.sh`\n- **Setup**（source_file）：from setuptools import find packages, setup 证据：`setup.py`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `frontend/package.json`, `CONTRIBUTING.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `frontend/package.json`, `CONTRIBUTING.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Introduction to Verba**：importance `high`\n  - source_paths: README.md, CHANGELOG.md, goldenverba/verba_manager.py\n- **RAG Concepts in Verba**：importance `high`\n  - source_paths: goldenverba/components/interfaces.py, goldenverba/components/types.py\n- **Component Architecture**：importance `high`\n  - source_paths: goldenverba/components/__init__.py, goldenverba/components/interfaces.py, goldenverba/components/managers.py\n- **Data Ingestion System**：importance `high`\n  - source_paths: goldenverba/components/reader/BasicReader.py, goldenverba/components/reader/UnstructuredAPI.py, goldenverba/components/reader/FirecrawlReader.py, goldenverba/components/reader/AssemblyAIAPI.py, goldenverba/components/reader/GitReader.py\n- **Chunking Strategies**：importance `high`\n  - source_paths: goldenverba/components/chunking/TokenChunker.py, goldenverba/components/chunking/SentenceChunker.py, goldenverba/components/chunking/SemanticChunker.py, goldenverba/components/chunking/RecursiveChunker.py, goldenverba/components/chunking/MarkdownChunker.py\n- **Embedding and Vector Storage**：importance `high`\n  - source_paths: goldenverba/components/embedding/OpenAIEmbedder.py, goldenverba/components/embedding/CohereEmbedder.py, goldenverba/components/embedding/OllamaEmbedder.py, goldenverba/components/embedding/SentenceTransformersEmbedder.py, goldenverba/components/embedding/WeaviateEmbedder.py\n- **RAG Retrieval System**：importance `high`\n  - source_paths: goldenverba/components/retriever/WindowRetriever.py, goldenverba/components/retriever/__init__.py, goldenverba/verba_manager.py, frontend/app/components/Document/DocumentExplorer.tsx, frontend/app/components/Document/VectorView.tsx\n- **LLM Generators and Answer Generation**：importance `high`\n  - source_paths: goldenverba/components/generation/OpenAIGenerator.py, goldenverba/components/generation/AnthrophicGenerator.py, goldenverba/components/generation/CohereGenerator.py, goldenverba/components/generation/GroqGenerator.py, goldenverba/components/generation/OllamaGenerator.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `6695928e1a9341086f7cf61bd5881a546c203b3c`\n- inspected_files: `Dockerfile`, `README.md`, `docker-compose.yml`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：1.0.1 Beautiful Verba\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.0.1 Beautiful Verba\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_b08b22b1d7404da6ae9d8153c53602cd | https://github.com/weaviate/Verba/releases/tag/1.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：v0.4.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.4.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_199393ab54bc4fd79d576c42dc3198f2 | https://github.com/weaviate/Verba/releases/tag/0.4.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：v1.0.3\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.3\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_90c577983a844f3ba246a181a8e03997 | https://github.com/weaviate/Verba/releases/tag/v1.0.3 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v2.1.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_0ec01ecbe8494b08a039e08f6bf68f01 | https://github.com/weaviate/Verba/releases/tag/v2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:672002598 | https://github.com/weaviate/Verba | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:672002598 | https://github.com/weaviate/Verba | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | github_repo:672002598 | https://github.com/weaviate/Verba | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:672002598 | https://github.com/weaviate/Verba | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：v0.3.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.3.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_29616574b8474fb7a44c6d3350b062fd | https://github.com/weaviate/Verba/releases/tag/0.3.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
      "summary": "给宿主 AI 的上下文和工作边界。",
      "title": "AI Context Pack / 带给我的 AI"
    },
    "boundary_risk_card": {
      "asset_id": "boundary_risk_card",
      "filename": "BOUNDARY_RISK_CARD.md",
      "markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：weaviate/Verba\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：1.0.1 Beautiful Verba（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v0.4.0（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v1.0.3（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v2.1.0（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
      "summary": "安装、权限、验证和推荐前风险。",
      "title": "Boundary & Risk Card / 边界与风险卡"
    },
    "human_manual": {
      "asset_id": "human_manual",
      "filename": "HUMAN_MANUAL.md",
      "markdown": "# https://github.com/weaviate/Verba 项目说明书\n\n生成时间：2026-05-15 15:59:59 UTC\n\n## 目录\n\n- [Introduction to Verba](#page-introduction)\n- [RAG Concepts in Verba](#page-rag-concepts)\n- [Component Architecture](#page-component-architecture)\n- [Data Ingestion System](#page-data-ingestion)\n- [Chunking Strategies](#page-chunking-strategies)\n- [Embedding and Vector Storage](#page-embedding-system)\n- [RAG Retrieval System](#page-retrieval-system)\n- [LLM Generators and Answer Generation](#page-llm-generators)\n- [Embedder Configuration](#page-embedders)\n- [Frontend Component Overview](#page-frontend-components)\n\n<a id='page-introduction'></a>\n\n## Introduction to Verba\n\n### 相关页面\n\n相关主题：[RAG Concepts in Verba](#page-rag-concepts)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n- [frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n- [frontend/app/components/Login/GettingStarted.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/GettingStarted.tsx)\n- [frontend/app/components/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n- [frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n- [PYTHON_TUTORIAL.md](https://github.com/weaviate/Verba/blob/main/PYTHON_TUTORIAL.md)\n</details>\n\n# Introduction to Verba\n\n## Overview\n\nVerba (The Golden RAGtriever) is an open-source, user-friendly RAG (Retrieval-Augmented Generation) application developed by Weaviate. It provides a streamlined interface for building and interacting with vector databases, enabling users to explore datasets and extract insights through semantic search and generative AI capabilities.\n\nThe application is designed to be accessible to both technical and non-technical users, offering multiple deployment options and integration with various LLM providers. Verba supports Python versions 3.10.0 to 3.12.0 and is distributed as the `goldenverba` Python package.\n\n| Property | Value |\n|----------|-------|\n| **Package Name** | goldenverba |\n| **Current Version** | 2.1.3 |\n| **Python Support** | >=3.10.0, <3.13.0 |\n| **Repository** | https://github.com/weaviate/Verba |\n| **License** | BSD License |\n\n资料来源：[setup.py:3-14](https://github.com/weaviate/Verba/blob/main/setup.py)\n\n## Core Features\n\nVerba provides a comprehensive set of features for RAG-based applications:\n\n### Data Import and Management\n\nUsers can import documents through multiple methods:\n- **Add Files**: Upload individual files directly\n- **Add Directory**: Import entire folders of documents\n- **Add URL**: Fetch content from web sources\n\nThe system automatically chunks and processes documents, making them searchable and queryable. Supported file formats include text files, PDFs, CSV, XLSX, and XLS formats for the DefaultReader.\n\n资料来源：[README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n\n### Chat Interface\n\nThe Chat page enables users to ask questions about their imported data. The system retrieves relevant document chunks and generates contextual responses using the configured LLM. The chat interface displays:\n\n- Real-time retrieval and generation status\n- Cached results indicator for faster subsequent queries\n- Source attribution for retrieved information\n- Code block syntax highlighting in responses\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n\n### Document Explorer\n\nUsers can browse, view, and manage imported documents through the Document Explorer. Each document displays:\n\n- Document metadata and labels\n- Chunk information with relevancy scores\n- Source links for reference\n- Content preview with Markdown rendering\n\n资料来源：[frontend/app/components/Document/ContentView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Document/ContentView.tsx)\n\n### Configuration Options\n\nVerba allows granular configuration of the RAG pipeline, including:\n\n- LLM provider selection\n- Embedding model configuration\n- Retrieval parameters\n- Chunk size and overlap settings\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n    A[User Interface - React Frontend] --> B[FastAPI Backend Server]\n    B --> C[Verba Manager - Core Logic]\n    C --> D[Weaviate Vector Database]\n    \n    E[LLM Providers] --> B\n    F[Ollama / HuggingFace] --> B\n    \n    G[Document Readers] --> C\n    H[Embedders] --> C\n    I[Generators] --> C\n    \n    D --> G\n    D --> H\n    D --> I\n```\n\n## Deployment Options\n\nVerba supports four deployment configurations to accommodate different use cases and infrastructure requirements.\n\n| Deployment Type | Description | Use Case |\n|-----------------|-------------|----------|\n| **Weaviate** | Connect to Weaviate Cloud Services (WCS) | Production deployments with managed infrastructure |\n| **Docker** | Run with Docker Compose | Containerized deployments |\n| **Local** | Run entirely on local machine | Development and testing |\n| **Custom** | Specify custom Weaviate URL and credentials | Integration with existing Weaviate instances |\n\n资料来源：[frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n\n### Environment Variables\n\nConfiguration can be managed through environment variables for automated deployments:\n\n| Variable | Description |\n|----------|-------------|\n| `DEFAULT_DEPLOYMENT` | Pre-select deployment type (Local, Docker, Weaviate, Custom) |\n| `OLLAMA_MODEL` | Default Ollama model name |\n| `OLLAMA_EMBED_MODEL` | Default Ollama embedding model |\n\n资料来源：[CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n## Supported Integrations\n\n### LLM Providers\n\nVerba integrates with multiple LLM providers for text generation:\n\n- **OpenAI**: GPT models with dynamic model name retrieval based on API key and URL\n- **Anthropic**: Claude models\n- **Cohere**: Command models\n- **Groq**: Fast inference API\n- **Novita AI**: Additional generative capabilities\n- **Upstage**: Reader, Embedder, and Generator support\n\n资料来源：[README.md](https://github.com/weaviate/Verba/blob/main/README.md) and [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n### Embedding Providers\n\nFor vector embeddings, Verba supports:\n\n- **Ollama**: Local embedding models\n- **HuggingFace**: Sentence transformers and other models\n- **OpenAI**: text-embedding-ada-002 and newer models\n- **Upstage**: Solar embedding models\n\n### Document Readers\n\nThe system includes specialized readers for various file formats:\n\n- **AssemblyAI**: Audio file transcription and processing\n- **DefaultReader**: Text, PDF, CSV, XLSX, XLS formats\n- **Unstructured**: Advanced document parsing capabilities\n\n## Installation Methods\n\n### Install via pip\n\n```bash\npip install goldenverba\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/weaviate/Verba\ncd Verba\npip install -e .\n```\n\n### Deploy with Docker\n\n```bash\ngit clone https://github.com/weaviate/Verba\ndocker compose --env-file <your-env-file> up -d --build\n```\n\n资料来源：[README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n\n## Project Structure\n\nThe Verba project is organized into two main components:\n\n```\nVerba/\n├── goldenverba/          # Python backend package\n│   └── server/           # FastAPI server implementation\n├── frontend/             # React TypeScript frontend\n│   └── app/\n│       ├── components/   # React components\n│       │   ├── Chat/     # Chat interface components\n│       │   ├── Document/ # Document explorer components\n│       │   ├── Ingestion/# Data import components\n│       │   ├── Login/    # Authentication views\n│       │   ├── Navigation/ # Navigation components\n│       │   └── Settings/ # Configuration components\n│       └── page.tsx      # Main application page\n├── setup.py              # Package configuration\n└── README.md             # Project documentation\n```\n\n## User Interface Navigation\n\nThe main navigation includes the following sections:\n\n| Navigation Item | Description |\n|-----------------|-------------|\n| **Chat** | Query imported data using RAG |\n| **Documents** | Browse and manage imported documents |\n| **Import Data** | Add new files, directories, or URLs |\n| **Settings** | Configure Verba and manage collections |\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n\n## Settings and Management\n\nThe Settings page provides administrative functions for Verba management:\n\n### Collections Management\n\nView all Weaviate collections with their object counts and status information, including shard configuration.\n\n### Reset Operations\n\n| Operation | Description |\n|-----------|-------------|\n| **Reset Documents** | Clears all documents and chunks from Verba |\n| **Reset Config** | Resets configuration to default values |\n| **Reset Verba** | Deletes all Verba-related collections |\n| **Reset Suggestions** | Clears autocomplete suggestion data |\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Settings/InfoView.tsx)\n\n## Getting Started Workflow\n\n```mermaid\ngraph LR\n    A[Install Verba] --> B[Configure Deployment]\n    B --> C[Set API Keys]\n    C --> D[Import Data]\n    D --> E[Configure RAG Pipeline]\n    E --> F[Query Data]\n```\n\n1. **Installation**: Choose an installation method (pip, source, or Docker)\n2. **Deployment Configuration**: Select deployment type (Weaviate, Docker, Local, or Custom)\n3. **API Keys**: Configure required API keys in `.env` file or through the UI\n4. **Data Import**: Import documents using Add Files, Add Directory, or Add URL\n5. **Configuration**: Adjust RAG pipeline settings under the Config tab\n6. **Query**: Ask questions and receive answers with relevant document citations\n\n资料来源：[README.md](https://github.com/weaviate/Verba/blob/main/README.md) and [frontend/app/components/Login/GettingStarted.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/GettingStarted.tsx)\n\n## Version History\n\n| Version | Release | Key Features |\n|---------|---------|--------------|\n| 2.1.3 | Latest | OLLAMA_MODEL, OLLAMA_EMBED_MODEL env vars, CSV/XLSX/XLS support, Hiding Getting Started display |\n| 2.1.2 | Previous | Novita Generator support, basic Document class tests, spaCy fixes |\n| 2.1.1 | Earlier | Dynamic OpenAI model retrieval |\n| 2.1.0 | Earlier | Upstage integration, Custom deployment, Groq support, AssemblyAI Reader |\n\n资料来源：[CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n## External Resources\n\n| Resource | URL |\n|----------|-----|\n| GitHub Repository | https://github.com/weaviate/Verba |\n| Blog Post | https://weaviate.io/blog/verba-open-source-rag-app |\n| Video Tutorial | https://www.youtube.com/watch?v=swKKRdLBhas |\n| Weaviate Forum | https://forum.weaviate.io/ |\n\n## Contributing\n\nVerba is an open-source community project. Contributions are welcome through:\n\n- GitHub Issues for bug reports\n- GitHub Discussions for feature requests and ideas\n- Pull Requests for code contributions\n\nBefore contributing, please review the Contribution Guide in the repository.\n\n---\n\n<a id='page-rag-concepts'></a>\n\n## RAG Concepts in Verba\n\n### 相关页面\n\n相关主题：[Introduction to Verba](#page-introduction), [RAG Retrieval System](#page-retrieval-system), [LLM Generators and Answer Generation](#page-llm-generators)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n- [frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n- [frontend/app/components/Chat/ChatMessage.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatMessage.tsx)\n- [frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n- [frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n</details>\n\n# RAG Concepts in Verba\n\nVerba (The Golden RAGtriever) is an open-source RAG (Retrieval-Augmented Generation) application designed to provide a streamlined, user-friendly interface for building and interacting with RAG-powered applications. This document explains the core RAG concepts implemented within Verba's architecture.\n\n## What is RAG?\n\nRetrieval-Augmented Generation (RAG) is a pattern that combines the power of large language models (LLMs) with external knowledge retrieval. Instead of relying solely on a model's training data, RAG systems:\n\n1. **Retrieve** relevant documents or chunks from a knowledge base\n2. **Augment** the user's query with the retrieved context\n3. **Generate** a response using the LLM with the augmented input\n\n资料来源：[README.md:1]()\n\n## Verba's RAG Pipeline Architecture\n\nVerba implements a complete RAG pipeline with configurable components for reading, embedding, chunking, and generating.\n\n```mermaid\ngraph TD\n    A[User Query] --> B[Retrieval Phase]\n    B --> C[Vector Search in Weaviate]\n    C --> D[Retrieve Relevant Chunks]\n    D --> E[Augment Query with Context]\n    E --> F[Generation Phase]\n    F --> G[LLM Response]\n    \n    H[Document Ingestion] --> I[Readers]\n    I --> J[Chunking]\n    J --> K[Embedding]\n    K --> L[Vector Storage in Weaviate]\n```\n\n资料来源：[README.md:1]()\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:1]()\n\n## Core Components\n\n### Readers\n\nVerba supports multiple document formats through its reader system. Documents can be imported via the frontend and processed by appropriate readers.\n\n| File Type | Format | Support Status |\n|-----------|--------|----------------|\n| CSV | `csv` | Supported (v2.1.3+) |\n| Excel | `xlsx`, `xls` | Supported (v2.1.3+) |\n| Text | Plain text | Supported |\n| Markdown | `.md` | Supported |\n| PDF | `.pdf` | Supported |\n| Audio | Various | Supported via AssemblyAI |\n\n资料来源：[CHANGELOG.md:8-13]()\n\n### Embedders\n\nVerba supports multiple embedding providers for converting documents into vector representations:\n\n- **OpenAI** - Uses OpenAI's embedding models\n- **Ollama** - Local embeddings via Ollama\n- **HuggingFace** - Sentence transformers from HuggingFace\n- **Cohere** - Cohere's embedding models\n- **Upstage** - Upstage's embedding service\n\n资料来源：[README.md:1]()\n资料来源：[CHANGELOG.md:15-22]()\n\n### Generators\n\nMultiple LLM providers are supported for generating responses:\n\n| Provider | Type | Configuration |\n|----------|------|---------------|\n| OpenAI | Cloud | API Key required |\n| Anthropic | Cloud | API Key required |\n| Cohere | Cloud | API Key required |\n| Groq | Cloud | API Key required |\n| Novita | Cloud | API Key required (v2.1.2+) |\n| Ollama | Local | No API Key needed |\n| Upstage | Cloud | API Key required |\n\n资料来源：[CHANGELOG.md:15-22]()\n资料来源：[frontend/app/components/Login/LoginView.tsx:1]()\n\n## Document Ingestion Workflow\n\nWhen users import documents into Verba, the following workflow is executed:\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Frontend\n    participant Reader\n    participant Chunker\n    participant Embedder\n    participant Weaviate\n    \n    User->>Frontend: Upload Document\n    Frontend->>Reader: Process File\n    Reader->>Chunker: Raw Text\n    Chunker->>Embedder: Text Chunks\n    Embedder->>Weaviate: Vector Embeddings\n    Weaviate->>Weaviate: Store Chunks + Vectors\n```\n\n### Chunking Configuration\n\nDocuments are split into manageable chunks for retrieval. Each chunk contains:\n\n- **Content** - The text content\n- **Chunk ID** - Position in original document\n- **Labels** - User-defined labels for categorization\n- **Source Link** - Reference to original document location\n- **Metadata** - Additional document properties\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1]()\n\n## Retrieval and Query Flow\n\n### Chat Interface\n\nVerba's chat interface handles the retrieval and generation process:\n\n```mermaid\ngraph LR\n    A[User Input] --> B[Socket Connection]\n    B --> C{Retrieval Phase}\n    C -->|Fetching Status: CHUNKS| D[Vector Search]\n    D --> E[Retrieve Top-K Chunks]\n    E --> F{Generation Phase}\n    F -->|Fetching Status: RESPONSE| G[LLM Processing]\n    G --> H[Stream Response]\n    H --> I[Display to User]\n```\n\nThe chat interface displays retrieval status to users:\n\n```typescript\nfetchingStatus === \"CHUNKS\" → \"Retrieving...\"\nfetchingStatus === \"RESPONSE\" → \"Generating...\"\n```\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:1]()\n\n### Message Types\n\nVerba supports multiple message types in the chat:\n\n| Type | Direction | Description |\n|------|-----------|-------------|\n| `user` | User → System | User queries |\n| `system` | System → User | LLM responses |\n| `error` | System → User | Error messages |\n| `retrieval` | System → User | Retrieved context |\n| `cached` | System → User | Cached responses |\n\n资料来源：[frontend/app/components/Chat/ChatMessage.tsx:1]()\n\n### Relevancy Scoring\n\nRetrieved chunks are scored for relevance. Chunks with a score greater than 0 are flagged as \"High Relevancy\":\n\n```tsx\n{contentSnippet.score > 0 && (\n  <div className=\"flex gap-2 items-center p-3 bg-primary-verba rounded-full w-fit\">\n    <HiSparkles size={12} />\n    <p className=\"text-xs flex text-text-verba\">High Relevancy</p>\n  </div>\n)}\n```\n\n资料来源：[frontend/app/components/Document/ContentView.tsx:1]()\n\n## Deployment Options\n\nVerba supports multiple deployment configurations:\n\n| Deployment | Description | Use Case |\n|------------|-------------|----------|\n| **Local** | Runs entirely on local machine with Ollama | Development, Privacy |\n| **Docker** | Containerized deployment | Easy setup |\n| **Weaviate Cloud** | Managed Weaviate service | Production |\n| **Custom** | User-provided Weaviate instance | Enterprise |\n\n资料来源：[README.md:1]()\n资料来源：[frontend/app/components/Login/LoginView.tsx:1]()\n\n### Environment Variables\n\nKey environment variables for RAG configuration:\n\n| Variable | Description |\n|----------|-------------|\n| `OLLAMA_MODEL` | Default Ollama model |\n| `OLLAMA_EMBED_MODEL` | Ollama embedding model |\n| `DEFAULT_DEPLOYMENT` | Default deployment type |\n| `WEAVIATE_URL` | Weaviate instance URL |\n| `WEAVIATE_API_KEY` | Weaviate API key |\n\n资料来源：[CHANGELOG.md:8-13]()\n\n## Configuration Management\n\nThe RAG pipeline can be configured through the Settings interface:\n\n```mermaid\ngraph TD\n    A[Settings Page] --> B[Config Tab]\n    A --> C[Info Tab]\n    A --> D[Collections Tab]\n    \n    B --> E[RAG Pipeline Settings]\n    C --> F[System Information]\n    D --> G[Weaviate Collections]\n    \n    E --> H[Embedder Selection]\n    E --> I[Generator Selection]\n    E --> J[Retrieval Settings]\n```\n\n### Configurable Options\n\n- **Embedder** - Choose embedding provider and model\n- **Generator** - Select LLM provider and model\n- **Retrieval** - Configure top-k, similarity thresholds\n- **Chunk Size** - Adjust document chunking parameters\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:1]()\n\n## Data Storage\n\n### Weaviate Collections\n\nVerba automatically creates collections in Weaviate for:\n\n- **Documents** - Original document metadata\n- **Chunks** - Vectorized document chunks with embeddings\n- **Configurations** - RAG pipeline settings\n\nEach collection tracks:\n- Object count\n- Shard configuration\n- Status\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:1]()\n\n## Reset Operations\n\nVerba provides granular reset capabilities:\n\n| Operation | Scope | Action |\n|-----------|-------|--------|\n| Reset Documents | Data | Clears all documents and chunks |\n| Reset Config | Configuration | Restores default RAG settings |\n| Reset Verba | System | Deletes all Verba collections |\n| Reset Suggestions | UI | Clears autocomplete cache |\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:1]()\n\n## Summary\n\nVerba implements a complete RAG pipeline with:\n\n- **Multi-format document support** - CSV, Excel, PDF, audio files\n- **Flexible embedding options** - Multiple cloud and local providers\n- **Diverse LLM integration** - OpenAI, Anthropic, Cohere, Ollama, and more\n- **Visual chat interface** - Real-time status updates during retrieval and generation\n- **Configurable pipeline** - Adjust chunking, embedding, and retrieval parameters\n- **Multiple deployment modes** - Local, Docker, Weaviate Cloud, or custom infrastructure\n\nThe system leverages Weaviate's vector database capabilities for efficient similarity search while providing a user-friendly interface for non-technical users to build and interact with RAG applications.\n\n---\n\n<a id='page-component-architecture'></a>\n\n## Component Architecture\n\n### 相关页面\n\n相关主题：[Data Ingestion System](#page-data-ingestion), [Chunking Strategies](#page-chunking-strategies), [Embedder Configuration](#page-embedders), [LLM Generators and Answer Generation](#page-llm-generators)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n- [frontend/app/components/Ingestion/FileSelectionView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/FileSelectionView.tsx)\n- [frontend/app/components/Settings/InfoView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Settings/InfoView.tsx)\n- [frontend/app/components/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n- [frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n- [README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n</details>\n\n# Component Architecture\n\n## Overview\n\nVerba (Golden RAGtriever) is a RAG (Retrieval-Augmented Generation) application built with a modular component architecture that separates concerns across ingestion, retrieval, and generation pipelines. The system enables users to import various data formats, process them into searchable chunks, and query them using configurable LLM-based chat interfaces. The frontend is built with React/Next.js and TypeScript, while the backend is powered by Python with FastAPI and Weaviate as the vector database.\n\nThe component architecture in Verba follows a plugin-based pattern where different readers, embedders, chunkers, and generators can be dynamically configured and swapped at runtime. This design allows extensibility without modifying core system code.\n\n## System Architecture\n\n```mermaid\ngraph TD\n    subgraph Frontend[\"Frontend (Next.js/React)\"]\n        Login[LoginView]\n        Chat[ChatInterface]\n        Ingest[FileSelectionView]\n        Settings[InfoView]\n        Nav[NavbarComponent]\n    end\n\n    subgraph Backend[\"Backend (Python/FastAPI)\"]\n        API[FastAPI Server]\n        Manager[Component Manager]\n        Components[Components Registry]\n    end\n\n    subgraph External[\"External Services\"]\n        Weaviate[Weaviate DB]\n        LLMs[LLM Providers]\n        Readers[Data Readers]\n    end\n\n    Login --> |Credentials| API\n    Chat --> |Query/RAGConfig| API\n    Ingest --> |FileData| API\n    Settings --> |Reset/Config| API\n    API --> Manager\n    Manager --> Components\n    Components --> Weaviate\n    Components --> LLMs\n    Components --> Readers\n```\n\n## Core Component Types\n\nVerba's component system is organized around four primary types that form the RAG pipeline:\n\n| Component Type | Purpose | Examples |\n|----------------|---------|----------|\n| **Reader** | Parse various data formats into text | DefaultReader, AssemblyAI, Unstructured |\n| **Embedder** | Convert text to vector representations | OpenAI Embedder, HuggingFace, Ollama |\n| **Chunker** | Split documents into manageable pieces | DefaultChunker |\n| **Generator** | Produce natural language responses | OpenAI Generator, Anthropic, Novita, Groq |\n\n## Component Manager Architecture\n\nThe component manager (`goldenverba/components/managers.py`) serves as the central registry and orchestrator for all pluggable components. It maintains references to available readers, embedders, chunkers, and generators, enabling runtime selection based on user configuration.\n\nComponents are registered through the `__init__.py` module which discovers and loads all available implementations. The manager provides methods to:\n\n- List available components by type\n- Retrieve component configurations\n- Instantiate components with provided settings\n- Validate component compatibility\n\n## Frontend Component Architecture\n\n### Navigation Structure\n\nThe frontend uses a page-based navigation system where `NavbarComponent` manages the main routing between different views:\n\n```mermaid\ngraph LR\n    Nav[NavbarComponent] --> |CHAT| ChatPage[ChatInterface]\n    Nav --> |DOCUMENTS| DocPage[DocumentExplorer]\n    Nav --> |ADD| AddPage[FileSelectionView]\n    Nav --> |SETTINGS| SettingsPage[InfoView]\n```\n\nNavigation items are conditionally rendered based on the `production` environment variable:\n\n- **Demo Mode**: Shows only Chat page\n- **Production/Local/Docker**: Shows Chat, Documents, Import Data, and Settings\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx]() (lines showing conditional rendering with `production != \"Demo\"`)\n\n### Login and Deployment Configuration\n\nThe `LoginView` component handles the initial setup flow, supporting multiple deployment types:\n\n| Deployment | Description | Configuration Required |\n|------------|-------------|----------------------|\n| Local | Standalone Weaviate instance | URL, API Key |\n| Docker | Containerized Weaviate | URL, API Key |\n| Weaviate Cloud (WCS) | Managed Weaviate service | URL, API Key |\n| Custom | User-specified Weaviate endpoint | URL, API Key, Port |\n\n资料来源：[frontend/app/components/Login/LoginView.tsx]() (lines 35-45 showing deployment type definitions)\n\n### Chat Interface Pipeline\n\nThe `ChatInterface` component implements the query-time RAG workflow:\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant ChatInterface\n    participant Backend\n    participant Weaviate\n    participant LLM\n    \n    User->>ChatInterface: Submit Query\n    ChatInterface->>Backend: /query with RAGConfig\n    Backend->>Weaviate: Vector Search\n    Weaviate->>Backend: Top-k Chunks\n    Backend->>LLM: Context + Query\n    LLM->>Backend: Generated Response\n    Backend->>ChatInterface: Response + Chunks\n    ChatInterface->>User: Display Results\n```\n\nThe interface displays retrieval status messages:\n- `CHUNKS` state: \"Retrieving...\" while fetching from Weaviate\n- `RESPONSE` state: \"Generating...\" while LLM produces answer\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx]() (lines showing fetchingStatus states)\n\n### Data Ingestion Flow\n\nThe `FileSelectionView` manages the document import pipeline:\n\n```mermaid\ngraph TD\n    Files[Files/Directories/URLs] --> Reader[Reader Component]\n    Reader --> Chunker[Chunker Component]\n    Chunker --> Embedder[Embedder Component]\n    Embedder --> Weaviate[Weaviate Collection]\n```\n\nFile imports support multiple sources:\n- **Add Files**: Individual file upload\n- **Add Directory**: Batch directory ingestion\n- **Add URL**: Web content extraction\n\n资料来源：[frontend/app/components/Ingestion/FileSelectionView.tsx]() (lines showing URL dropdown with Reader component filtering)\n\n### Settings and Configuration\n\nThe `InfoView` component provides system management capabilities:\n\n| Action | Function | Data Affected |\n|--------|----------|---------------|\n| Reset Documents | Clear all collections | Documents, Chunks |\n| Reset Config | Restore default settings | RAGConfig |\n| Reset Verba | Full system reset | All collections |\n| Reset Suggestions | Clear autocomplete cache | Suggestion data |\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx]() (lines showing UserModalComponent triggers)\n\n## RAG Configuration Schema\n\nThe `RAGConfig` object defines the active pipeline configuration:\n\n```typescript\ninterface RAGConfig {\n  Reader: {\n    components: Record<string, Component>;\n  };\n  Chunker: {\n    components: Record<string, Component>;\n  };\n  Embedder: {\n    components: Record<string, Component>;\n  };\n  Generator: {\n    components: Record<string, Component>;\n  };\n}\n```\n\nEach component contains:\n- `type`: Component category (e.g., \"URL\", \"Text\", \"Vector\")\n- `name`: Human-readable identifier\n- `settings`: Key-value configuration parameters\n\n## State Management\n\nVerba manages state through React props and context patterns:\n\n```mermaid\ngraph TD\n    App[App Root] --> |Credentials| LoginView\n    App --> |RAGConfig| ChatInterface\n    App --> |Themes| Components\n    App --> |production| NavbarComponent\n    \n    ChatInterface --> |setRAGConfig| App\n    LoginView --> |setIsLoggedIn| App\n```\n\nKey state objects:\n- **Credentials**: Weaviate connection details (URL, API key)\n- **RAGConfig**: Pipeline configuration for all component types\n- **Themes**: UI theming configuration\n- **production**: Deployment mode (\"Local\" | \"Demo\" | \"Production\")\n\n## Dependency Injection\n\nThe frontend components receive dependencies via constructor injection:\n\n```typescript\ninterface ChatInterfaceProps {\n  credentials: Credentials;\n  RAGConfig: RAGConfig | null;\n  setRAGConfig: (config: RAGConfig | null) => void;\n  production: \"Local\" | \"Demo\" | \"Production\";\n  addStatusMessage: (message: string) => void;\n}\n```\n\nThis pattern enables:\n- Testability through mock injection\n- Flexible component composition\n- Runtime configuration changes\n\n## WebSocket Communication\n\nReal-time updates between frontend and backend use WebSocket connections:\n\n- Connection status monitoring via `socketOnline` and `socketStatus`\n- Status updates: \"ONLINE\", \"OFFLINE\", \"CONNECTING\"\n- Ability to cancel ongoing operations (e.g., retrieval/generation)\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx]() (lines showing socket status handling)\n\n## Conclusion\n\nThe Verba component architecture demonstrates a clean separation between frontend presentation and backend processing, with a plugin-based system enabling flexible RAG pipeline configuration. The architecture supports multiple deployment scenarios, various data sources, and different LLM providers through abstracted component interfaces.\n\n---\n\n<a id='page-data-ingestion'></a>\n\n## Data Ingestion System\n\n### 相关页面\n\n相关主题：[Chunking Strategies](#page-chunking-strategies), [Embedding and Vector Storage](#page-embedding-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [goldenverba/components/document.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/document.py)\n- [goldenverba/components/reader/HTMLReader.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/reader/HTMLReader.py)\n- [frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n- [frontend/app/components/Ingestion/FileSelectionView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/FileSelectionView.tsx)\n- [frontend/app/components/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n</details>\n\n# Data Ingestion System\n\nThe Data Ingestion System in Verba (The Golden RAGtriever) is responsible for accepting user-provided documents from various sources, processing them through configurable reader pipelines, and preparing them for embedding and retrieval. This system forms the entry point of the RAG pipeline, enabling users to import files, URLs, directories, and audio content into the application.\n\n## System Overview\n\nThe ingestion system operates as a multi-stage pipeline that transforms raw content into structured `Document` objects ready for vectorization. It supports multiple input types and allows per-file configuration of chunking, embedding, and reading strategies.\n\nThe architecture consists of three primary layers:\n\n| Layer | Responsibility | Key Components |\n|-------|---------------|----------------|\n| **Frontend** | User interface for file selection and configuration | `FileSelectionView`, `BasicSettingView`, `NavbarComponent` |\n| **API** | Backend endpoint handling and request processing | `server/api.py` |\n| **Readers** | Content extraction from various file types and sources | `BasicReader`, `HTMLReader`, `UnstructuredAPI`, `AssemblyAIAPI`, etc. |\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:1-50]()\n\n## Ingestion Flow\n\n```mermaid\ngraph TD\n    A[User clicks Import Data] --> B[FileSelectionView]\n    B --> C{Input Type}\n    C -->|Files| D[Add Files Tab]\n    C -->|Directory| E[Add Directory Tab]\n    C -->|URLs| F[Add URL Tab]\n    D --> G[BasicSettingView - Configure]\n    E --> G\n    F --> G\n    G --> H[Select Reader Type]\n    G --> I[Set Chunker]\n    G --> J[Set Embedder]\n    G --> K[Add Metadata & Labels]\n    K --> L[Import Selected]\n    L --> M[API Endpoint: /import]\n    M --> N[Reader Processing]\n    N --> O[Document Creation]\n    O --> P[Chunking]\n    P --> Q[Vector Storage in Weaviate]\n```\n\n## Document Model\n\nThe core data structure used throughout ingestion is the `Document` class, defined in `goldenverba/components/document.py`. This class encapsulates all metadata and content associated with an ingested document.\n\n```python\nDocument(\n    title=str,\n    content=str,\n    extension=str,\n    labels=list,\n    source=str,\n    fileSize=int,\n    metadata=str,\n    meta=dict\n)\n```\n\n资料来源：[goldenverba/components/document.py:1-100]()\n\n### Document Creation from Configuration\n\nThe `create_document` function provides a factory method for generating `Document` objects from file configuration:\n\n```python\ndef create_document(content: str, fileConfig: FileConfig) -> Document:\n    return Document(\n        title=fileConfig.filename,\n        content=content,\n        extension=fileConfig.extension,\n        labels=fileConfig.labels,\n        source=fileConfig.source,\n        fileSize=fileConfig.file_size,\n        metadata=fileConfig.metadata,\n        meta={},\n    )\n```\n\n资料来源：[goldenverba/components/document.py:100-115]()\n\n## Reader Components\n\nReaders are responsible for extracting raw content from various input sources. Each reader implements a specific loading strategy and returns a list of `Document` objects.\n\n### Available Readers\n\n| Reader | Type | Supported Sources | Description |\n|--------|------|-------------------|-------------|\n| `BasicReader` | File | `.txt`, `.pdf`, `.docx`, `.xlsx`, `.xls`, `.csv` | Standard file reading for common document formats |\n| `HTMLReader` | URL | Web pages | Fetches and converts web pages, supports recursive crawling |\n| `UnstructuredAPI` | API | Multiple formats | Uses Unstructured.io API for complex document parsing |\n| `AssemblyAIAPI` | API | Audio files | Transcribes and extracts content from audio |\n| `GitReader` | Repository | Git repos | Clones and extracts documentation from Git repositories |\n| `UpstageDocumentParse` | API | Documents | Uses Upstage AI for document parsing |\n\n### HTMLReader Configuration\n\nThe HTMLReader supports advanced web scraping capabilities:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `URLs` | list | required | List of URLs to process |\n| `Convert To Markdown` | bool | true | Whether to convert HTML to markdown |\n| `Recursive` | bool | false | Whether to follow linked pages |\n| `Max Depth` | int | 3 | Maximum recursion depth for linked pages |\n\n资料来源：[goldenverba/components/reader/HTMLReader.py:1-80]()\n\n### HTMLReader Recursive Processing\n\n```python\nasync def process_url(\n    self,\n    url: str,\n    to_markdown: bool,\n    recursive: bool,\n    max_depth: int,\n    current_depth: int,\n    session: aiohttp.ClientSession,\n    reader: BasicReader,\n    fileConfig: FileConfig,\n    documents: List[Document],\n    processed_urls: set,\n):\n    if url in processed_urls or current_depth > max_depth:\n        return\n    \n    processed_urls.add(url)\n    # ... content fetching and document creation\n```\n\nThe reader uses an async pattern with `aiohttp.ClientSession` for efficient concurrent URL processing, maintaining a `processed_urls` set to prevent duplicate processing.\n\n资料来源：[goldenverba/components/reader/HTMLReader.py:80-120]()\n\n## Frontend Ingestion Interface\n\n### File Selection View\n\nThe `FileSelectionView` component provides the primary UI for selecting and managing files to ingest. It supports three input modes:\n\n```tsx\n<div className=\"tab-group\">\n  <Tabs \n    tabs={[\"Add Files\", \"Add Directory\", \"Add URL\"]}\n    onTabChange={handleTabChange}\n  />\n</div>\n```\n\nKey features include:\n- **File List Display**: Shows all selected files with their status\n- **Multi-file Selection**: Allows batch processing of multiple files\n- **URL Dropdown**: Provides reader type selection for URL inputs\n- **Import Actions**: Triggers the actual ingestion process\n\n资料来源：[frontend/app/components/Ingestion/FileSelectionView.tsx:1-100]()\n\n### Configuration Settings View\n\nThe `BasicSettingView` component provides per-file configuration options. Each file can have its own RAG pipeline configuration:\n\n| Setting | Description | UI Element |\n|---------|-------------|------------|\n| **Reader** | Content extraction method | Disabled text input showing selected reader |\n| **Chunker** | Text splitting strategy | Disabled text input with description |\n| **Embedder** | Vector embedding model | Disabled text input with description |\n| **Title** | Document display name | Editable text input |\n| **Source Link** | Original source reference | Editable text input |\n| **Labels** | Categorization tags | Input with add button |\n| **Metadata** | Custom key-value data | Textarea for JSON-like content |\n| **Overwrite** | Replace existing documents | Checkbox toggle |\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-150]()\n\n### Label Management\n\nLabels provide a way to categorize documents for filtering during retrieval:\n\n```tsx\n<input\n  type=\"text\"\n  value={label}\n  onChange={(e) => setLabel(e.target.value)}\n  onKeyDown={(e) => {\n    if (e.key === \"Enter\") {\n      e.preventDefault();\n      addLabel(label);\n    }\n  }}\n/>\n<VerbaButton\n  title=\"Add\"\n  Icon={IoAddCircleSharp}\n  onClick={() => addLabel(label)}\n/>\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:20-45]()\n\n### Debug Modal\n\nThe configuration includes a debug feature that displays the complete file configuration as JSON:\n\n```tsx\n<pre className=\"whitespace-pre-wrap text-xs\">\n  {selectedFileData\n    ? (() => {\n        const objCopy = { ...fileMap[selectedFileData] };\n        objCopy.content = \"File Content\";\n        return JSON.stringify(objCopy, null, 2);\n      })()\n    : \"\"}\n</pre>\n```\n\nThis allows users to inspect the full configuration state including the RAG pipeline settings before import.\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:100-130]()\n\n## Configuration Management\n\n### FileConfig Structure\n\nThe `FileConfig` object carries all configuration for a single file through the ingestion pipeline:\n\n| Field | Type | Purpose |\n|-------|------|---------|\n| `filename` | string | Document title |\n| `extension` | string | File type indicator |\n| `labels` | list | Categorization tags |\n| `source` | string | Original source URL/path |\n| `file_size` | int | Size in bytes |\n| `metadata` | string | Custom metadata string |\n| `rag_config` | dict | Reader, Chunker, Embedder settings |\n| `content` | string | Raw file content |\n| `overwrite` | bool | Whether to replace existing |\n\n### RAG Pipeline Configuration\n\nEach file maintains its own RAG configuration that specifies the processing pipeline:\n\n```tsx\nfileMap[selectedFileData].rag_config = {\n  \"Reader\": {\n    \"selected\": \"BasicReader\",\n    \"components\": {\n      \"BasicReader\": { \"type\": \"file\", \"description\": \"...\" },\n      \"HTMLReader\": { \"type\": \"URL\", \"description\": \"...\" }\n    }\n  },\n  \"Chunker\": {\n    \"selected\": \"DefaultChunker\",\n    \"components\": { ... }\n  },\n  \"Embedder\": {\n    \"selected\": \"OpenAIEmbedder\",\n    \"components\": { ... }\n  }\n}\n```\n\n## Navigation Integration\n\nThe ingestion system is accessible from the main navigation bar:\n\n```tsx\n{production != \"Demo\" && (\n  <NavbarButton\n    hide={false}\n    Icon={IoMdAddCircle}\n    title=\"Import Data\"\n    currentPage={currentPage}\n    setCurrentPage={setCurrentPage}\n    setPage=\"ADD\"\n  />\n)}\n```\n\nIn Demo mode, the import functionality is disabled to prevent unauthorized data ingestion.\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:30-45]()\n\n## State Management\n\nThe frontend maintains the ingestion state using React hooks:\n\n| State Variable | Type | Purpose |\n|---------------|------|---------|\n| `fileMap` | `Record<string, FileData>` | All files selected for ingestion |\n| `selectedFileData` | `string \\| null` | Currently selected file key |\n| `socketStatus` | `string` | Connection status to backend |\n| `currentPage` | `string` | Current navigation page |\n\nThe `FileData` interface contains both the raw content and the configuration:\n\n```tsx\ninterface FileData {\n  content: string;\n  filename: string;\n  extension: string;\n  labels: string[];\n  source: string;\n  file_size: number;\n  metadata: string;\n  rag_config: RAGConfig;\n  overwrite: boolean;\n  block: boolean;  // Disables editing during processing\n}\n```\n\n## Integration with RAG Pipeline\n\nAfter successful ingestion, documents flow into the RAG pipeline:\n\n1. **Reader** extracts raw content from the source\n2. **Chunker** splits content into smaller segments for retrieval\n3. **Embedder** converts chunks into vector embeddings\n4. **Weaviate** stores the embedded chunks for semantic search\n\nThis integration is configured per-file through the `rag_config` object, allowing different documents to use different processing strategies based on their content type or user requirements.\n\n## Error Handling\n\nThe HTMLReader demonstrates the error handling pattern used across readers:\n\n```python\nasync with aiohttp.ClientSession() as session:\n    for url in urls:\n        try:\n            await self.process_url(\n                url, to_markdown, recursive, max_depth,\n                0, session, reader, fileConfig, documents, processed_urls\n            )\n        except Exception as e:\n            msg.warn(f\"Failed to process URL {url}: {str(e)}\")\n```\n\nIndividual failures do not halt the entire ingestion process, allowing partial success scenarios.\n\n---\n\n<a id='page-chunking-strategies'></a>\n\n## Chunking Strategies\n\n### 相关页面\n\n相关主题：[Data Ingestion System](#page-data-ingestion), [Embedding and Vector Storage](#page-embedding-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [goldenverba/components/chunking/TokenChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/TokenChunker.py)\n- [goldenverba/components/chunking/SentenceChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/SentenceChunker.py)\n- [goldenverba/components/chunking/SemanticChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/SemanticChunker.py)\n- [goldenverba/components/chunking/RecursiveChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/RecursiveChunker.py)\n- [goldenverba/components/chunking/MarkdownChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/MarkdownChunker.py)\n- [goldenverba/components/chunking/HTMLChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/HTMLChunker.py)\n- [goldenverba/components/chunking/CodeChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/CodeChunker.py)\n- [goldenverba/components/chunking/JSONChunker.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/JSONChunker.py)\n- [goldenverba/components/chunking/__init__.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/chunking/__init__.py)\n</details>\n\n# Chunking Strategies\n\n## Overview\n\nChunking strategies in Verba define how documents are split into smaller, semantically coherent units for embedding and retrieval. Each strategy implements the `Chunker` interface and provides different approaches to partitioning document content based on structural markers, token counts, sentence boundaries, or semantic similarity.\n\nThe chunking system is designed to:\n\n- Break large documents into manageable pieces for embedding\n- Preserve contextual continuity through overlapping chunks\n- Respect document structure (headers, code blocks, HTML tags)\n- Provide configuration options for fine-tuning chunk sizes and overlap\n- Skip documents that already contain chunks to avoid redundant processing\n\n资料来源：[goldenverba/components/chunking/__init__.py]()\n\n## Architecture\n\n### Chunker Interface\n\nAll chunkers inherit from the `Chunker` base class and implement the `chunk()` async method. The interface accepts configuration parameters, a list of documents, and an optional embedder.\n\n```python\nclass Chunker:\n    name: str\n    requires_library: list[str]\n    description: str\n\n    async def chunk(\n        self,\n        config: dict,\n        documents: list[Document],\n        embedder: Embedding | None = None,\n        embedder_config: dict | None = None,\n    ) -> list[Document]:\n```\n\n### Chunk Data Model\n\nEach chunk produced by the chunkers contains the following fields:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `content` | str | Full chunk text including overlap |\n| `chunk_id` | int | Sequential identifier within the document |\n| `start_i` | int \\| None | Character-level start index |\n| `end_i` | int \\| None | Character-level end index |\n| `content_without_overlap` | str | Chunk text without overlap region |\n\n资料来源：[goldenverba/components/chunk.py]()\n\n## Available Chunking Strategies\n\n### 1. Token Chunker\n\nThe Token Chunker splits documents based on token counts using spaCy's tokenizer. It ensures chunks align with natural token boundaries for efficient embedding.\n\n**Key Features:**\n\n- Splits text by token count using spaCy NLP\n- Configurable tokens per chunk via `Tokens` configuration\n- Configurable overlap via `Overlap` configuration\n- Calculates precise character-level indices for chunk boundaries\n\n**Configuration Options:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `Tokens` | int | Number of tokens per chunk |\n| `Overlap` | int | Number of overlapping tokens between chunks |\n\n**Behavior:**\n\n- If `Tokens` exceeds document length or is zero, the entire document becomes a single chunk\n- If overlap exceeds tokens, overlap is clamped to `tokens - 1` with a warning\n- Chunk content includes overlap; `content_without_overlap` excludes the overlap region\n\n资料来源：[goldenverba/components/chunking/TokenChunker.py]()\n\n### 2. Sentence Chunker\n\nThe Sentence Chunker splits documents at sentence boundaries using spaCy's sentence segmentation. This preserves complete sentences within chunks.\n\n**Key Features:**\n\n- Sentence-level splitting using spaCy's `sents` property\n- Configurable sentences per chunk\n- Configurable overlap at sentence level\n- Character-level index tracking for precise boundaries\n\n**Configuration Options:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `Sentences` | int | Number of sentences per chunk |\n| `Overlap` | int | Number of overlapping sentences between chunks |\n\n**Behavior:**\n\n- Extracts all sentences from the document using spaCy\n- Joins sentences to form chunks while preserving overlap regions\n- Calculates character offsets accounting for spacing between sentences\n\n资料来源：[goldenverba/components/chunking/SentenceChunker.py]()\n\n### 3. Recursive Chunker\n\nThe Recursive Chunker uses LangChain's `RecursiveCharacterTextSplitter` to intelligently split text while attempting to preserve natural boundaries.\n\n**Key Features:**\n\n- Multi-level character-based splitting\n- Preserves chunk boundaries at logical text breaks\n- Configurable chunk size and overlap\n- Uses `keep Separator` parameter to retain separators in chunks\n\n资料来源：[goldenverba/components/chunking/RecursiveChunker.py]()\n\n### 4. Semantic Chunker\n\nThe Semantic Chunker groups content based on semantic similarity rather than fixed sizes or boundaries.\n\n**Key Features:**\n\n- Clusters sentences by semantic meaning\n- Dynamically determines chunk boundaries based on content similarity\n- Optimal for maintaining topical coherence\n\n资料来源：[goldenverba/components/chunking/SemanticChunker.py]()\n\n### 5. Markdown Chunker\n\nThe Markdown Chunker splits documents based on markdown header hierarchy using LangChain's `MarkdownHeaderTextSplitter`.\n\n**Supported Headers:**\n\n| Header Level | Syntax |\n|--------------|--------|\n| Header 1 | `#` |\n| Header 2 | `##` |\n| Header 3 | `###` |\n\n**Key Features:**\n\n- Splits at markdown header boundaries\n- Preserves header context by prepending headers to each chunk\n- Uses `get_header_values()` helper to extract header text from LangChain document metadata\n- Maintains hierarchical context through header inclusion\n\n**Header Extraction Logic:**\n\n```python\ndef get_header_values(split_doc: LangChainDocument) -> list[str]:\n    header_keys = [header_key for _, header_key in HEADERS_TO_SPLIT_ON]\n    return [\n        header_value\n        for header_key in header_keys\n        if (header_value := split_doc.metadata.get(header_key)) is not None\n    ]\n```\n\n资料来源：[goldenverba/components/chunking/MarkdownChunker.py]()\n\n### 6. HTML Chunker\n\nThe HTML Chunker splits documents based on HTML tag structure using LangChain's `HTMLHeaderTextSplitter`.\n\n**Supported Tags:**\n\n| Tag | Description |\n|-----|-------------|\n| `h1` | Header 1 |\n| `h2` | Header 2 |\n| `h3` | Header 3 |\n| `h4` | Header 4 |\n\n**Key Features:**\n\n- Splits at HTML header boundaries\n- Preserves header content within each chunk\n- Appends header text before page content\n- Requires `langchain_text_splitters` library\n\n**Chunk Text Construction:**\n\n```python\nchunk_text = \"\"\nif len(chunk.metadata) > 0:\n    chunk_text += list(chunk.metadata.values())[0] + \"\\n\"\nchunk_text += chunk.page_content\n```\n\n资料来源：[goldenverba/components/chunking/HTMLChunker.py]()\n\n### 7. Code Chunker\n\nThe Code Chunker is optimized for source code files, splitting based on code-specific structures and syntax.\n\n**Key Features:**\n\n- Language-aware splitting for code files\n- Preserves code structure and syntax context\n- Handles various programming language conventions\n\n资料来源：[goldenverba/components/chunking/CodeChunker.py]()\n\n### 8. JSON Chunker\n\nThe JSON Chunker splits JSON documents at logical structural boundaries.\n\n**Key Features:**\n\n- Splits at JSON object/array boundaries\n- Preserves nested structure context\n- Handles JSON-specific formatting\n\n资料来源：[goldenverba/components/chunking/JSONChunker.py]()\n\n## Chunking Workflow\n\n```mermaid\ngraph TD\n    A[Document Ingestion] --> B{Already Chunked?}\n    B -->|Yes| C[Skip Chunking]\n    B -->|No| D[Select Chunker Strategy]\n    D --> E{Chunking Strategy}\n    E -->|Token| F[TokenChunker]\n    E -->|Sentence| G[SentenceChunker]\n    E -->|Recursive| H[RecursiveChunker]\n    E -->|Semantic| I[SemanticChunker]\n    E -->|Markdown| J[MarkdownChunker]\n    E -->|HTML| K[HTMLChunker]\n    E -->|Code| L[CodeChunker]\n    E -->|JSON| M[JSONChunker]\n    F --> N[Split Document]\n    G --> N\n    H --> N\n    I --> N\n    J --> N\n    K --> N\n    L --> N\n    M --> N\n    N --> O[Create Chunk Objects]\n    O --> P[Append to document.chunks]\n    P --> Q[Return Modified Documents]\n```\n\n## Chunking Configuration\n\nEach chunker accepts a configuration dictionary with strategy-specific parameters:\n\n| Chunker | Primary Config | Overlap Config | Library Dependency |\n|---------|----------------|-----------------|---------------------|\n| Token | `Tokens` | `Overlap` | `spacy` |\n| Sentence | `Sentences` | `Overlap` | `spacy` |\n| Recursive | `Chunk Size` | `Overlap` | `langchain_text_splitters` |\n| Semantic | N/A | N/A | `langchain_text_splitters` |\n| Markdown | N/A | N/A | `langchain_text_splitters` |\n| HTML | N/A | N/A | `langchain_text_splitters` |\n| Code | N/A | N/A | `langchain_text_splitters` |\n| JSON | N/A | N/A | `langchain_text_splitters` |\n\n## Overlap Strategy\n\nOverlap enables context preservation between adjacent chunks, improving retrieval accuracy for queries that span chunk boundaries.\n\n**Overlap Calculation in TokenChunker:**\n\n```python\nwhile i < len(doc):\n    start_i = i\n    end_i = min(i + units + overlap, len(doc))\n    if end_i == len(doc):\n        overlap_start = end_i\n    else:\n        overlap_start = min(i + units, end_i)\n\n    chunk_text = doc[start_i:end_i].text\n    chunk_text_without_overlap = doc[start_i:overlap_start].text\n```\n\n**Overlap Calculation in SentenceChunker:**\n\n```python\noverlap_start = max(0, end_i - overlap)\nchunk_text = \" \".join(sentences[start_i:end_i])\nchunk_text_without_overlap = \" \".join(sentences[start_i:overlap_start])\n```\n\n资料来源：[goldenverba/components/chunking/TokenChunker.py](), [goldenverba/components/chunking/SentenceChunker.py]()\n\n## Skip Mechanism\n\nAll chunkers implement a document skipping mechanism to prevent redundant processing:\n\n```python\n# Skip if document already contains chunks\nif len(document.chunks) > 0:\n    continue\n```\n\nThis ensures idempotent chunking operations and allows manual chunk management.\n\n## Best Practices\n\n### Choosing a Chunker\n\n| Document Type | Recommended Chunker | Reason |\n|---------------|---------------------|--------|\n| Plain text | Token, Sentence, Recursive | General-purpose splitting |\n| Markdown files | Markdown | Respects header hierarchy |\n| HTML documents | HTML | Preserves HTML structure |\n| Source code | Code | Language-aware boundaries |\n| JSON data | JSON | Structural preservation |\n| Long-form content | Semantic | Topic coherence |\n| Conversational data | Sentence | Natural language boundaries |\n\n### Configuration Guidelines\n\n1. **Token/Sentence counts**: Start with 256-512 tokens or 3-5 sentences per chunk\n2. **Overlap**: Use 10-20% overlap for most use cases\n3. **Boundary alignment**: For token-based chunking, prefer natural token boundaries over character cuts\n\n## Dependencies\n\n| Library | Used By | Purpose |\n|---------|---------|---------|\n| `spacy` | TokenChunker, SentenceChunker, RecursiveChunker | NLP processing, tokenization, sentence segmentation |\n| `langchain_text_splitters` | MarkdownChunker, HTMLChunker, CodeChunker, JSONChunker, RecursiveChunker, SemanticChunker | Text splitting algorithms |\n\n资料来源：[goldenverba/components/chunking/TokenChunker.py](), [goldenverba/components/chunking/MarkdownChunker.py](), [goldenverba/components/chunking/HTMLChunker.py]()\n\n---\n\n<a id='page-embedding-system'></a>\n\n## Embedding and Vector Storage\n\n### 相关页面\n\n相关主题：[Chunking Strategies](#page-chunking-strategies), [RAG Retrieval System](#page-retrieval-system)\n\n<details>\n<summary>Relevant Source Files</summary>\n\nThe following source files were used to generate this documentation page:\n\n- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n- [frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n- [frontend/app/components/Chat/ChatConfig.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatConfig.tsx)\n- [goldenverba/components/document.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/document.py)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n</details>\n\n# Embedding and Vector Storage\n\nVerba implements a modular RAG (Retrieval-Augmented Generation) pipeline where embeddings play a critical role in transforming textual content into vector representations for semantic search and retrieval operations.\n\n## Overview\n\nEmbedding and vector storage in Verba enables the transformation of documents and their chunks into high-dimensional vector representations. These vectors power semantic search capabilities, allowing users to retrieve relevant content based on meaning rather than exact keyword matches. The system supports multiple embedding providers and integrates with Weaviate as the primary vector database.\n\n## Architecture\n\n```mermaid\ngraph TD\n    A[Document] --> B[Reader Component]\n    B --> C[Text Content]\n    C --> D[Chunker Component]\n    D --> E[Document Chunks]\n    E --> F[Embedder Component]\n    F --> G[Vector Embeddings]\n    G --> H[Weaviate Vector Store]\n    \n    I[User Query] --> J[Embedder Component]\n    J --> K[Query Vector]\n    K --> H\n    H --> L[Similarity Search]\n    L --> M[Retrieved Chunks]\n```\n\n## Embedder Components\n\nVerba supports multiple embedder implementations, allowing users to choose the provider that best fits their requirements.\n\n### Available Embedders\n\n| Embedder | Provider | Status |\n|----------|----------|--------|\n| OpenAI Embedder | OpenAI | Default |\n| Cohere Embedder | Cohere | Supported |\n| Ollama Embedder | Ollama | Supported |\n| SentenceTransformers Embedder | HuggingFace | Supported |\n| VoyageAI Embedder | VoyageAI | Supported |\n| Upstage Embedder | Upstage | Supported |\n| Google Embedder | Google | Supported |\n| Weaviate Embedder | Weaviate | Built-in |\n\n资料来源：[CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n### Embedder Selection\n\nThe embedder can be configured through the RAG configuration interface:\n\n```typescript\n<ComponentView\n  RAGConfig={RAGConfig}\n  component_name=\"Embedder\"\n  selectComponent={selectComponent}\n  updateConfig={updateConfig}\n  saveComponentConfig={saveComponentConfig}\n  blocked={production == \"Demo\"}\n/>\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatConfig.tsx)\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `OPENAI_API_KEY` | API key for OpenAI embeddings | For OpenAI |\n| `OPENAI_EMBED_API_KEY` | Separate API key for embeddings | Optional |\n| `OPENAI_EMBED_BASE_URL` | Custom endpoint for embeddings | Optional |\n| `OPENAI_CUSTOM_EMBED` | Flag for custom embedding models | Optional |\n| `COHERE_API_KEY` | API key for Cohere | For Cohere |\n| `VOYAGE_API_KEY` | API key for VoyageAI | For VoyageAI |\n| `UPSTAGE_API_KEY` | API key for Upstage | For Upstage |\n| `GOOGLE_API_KEY` | API key for Google | For Google |\n\n资料来源：[README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n\n### Custom OpenAI Embedding Configuration\n\nFor users deploying custom OpenAI-compatible embedding servers:\n\n```bash\nOPENAI_EMBED_API_KEY=YOUR_API_KEY\nOPENAI_EMBED_BASE_URL=YOUR_CUSTOM_URL\nOPENAI_CUSTOM_EMBED=true\n```\n\n资料来源：[README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n\n## Document Processing Pipeline\n\nThe embedding process is part of a larger document ingestion pipeline:\n\n```mermaid\ngraph LR\n    A[File Upload] --> B[Reader]\n    B --> C[Text Extraction]\n    C --> D[Chunking]\n    D --> E[Chunk Processing]\n    E --> F[Embedding Generation]\n    F --> G[Vector Storage]\n    G --> H[Indexing]\n```\n\n### Step 1: Document Reading\n\nDocuments are first processed by a Reader component that extracts text content based on file type. Supported formats include PDF, DOCX, TXT, CSV, XLSX, XLS, and more.\n\n### Step 2: Chunking\n\nExtracted text is split into smaller chunks using configurable chunking strategies. The chunker can be selected and configured per document.\n\n### Step 3: Embedding Generation\n\nEach chunk is passed through the selected embedder to generate a vector representation. The embedder transforms textual content into numerical vectors in a high-dimensional space.\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n\n## RAG Configuration\n\nVerba allows per-document RAG configuration including the embedder selection:\n\n```typescript\ninterface RAGConfig {\n  \"Reader\": {\n    selected: string;\n    components: Record<string, ComponentConfig>;\n  };\n  \"Chunker\": {\n    selected: string;\n    components: Record<string, ComponentConfig>;\n  };\n  \"Embedder\": {\n    selected: string;\n    components: Record<string, ComponentConfig>;\n  };\n  \"Retriever\": {\n    selected: string;\n    components: Record<string, ComponentConfig>;\n  };\n  \"Generator\": {\n    selected: string;\n    components: Record<string, ComponentConfig>;\n  };\n}\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n\n## Vector Storage in Weaviate\n\nVerba uses Weaviate as its vector database. The embeddings are stored alongside metadata for efficient similarity search operations.\n\n### Collection Management\n\nCollections in Weaviate store documents with their associated vectors:\n\n```python\n{\n    \"name\": \"collection_name\",\n    \"count\": number_of_objects,\n    \"status\": \"vector_status\",\n    \"shards\": number_of_shards\n}\n```\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Settings/InfoView.tsx)\n\n### Document Document Structure\n\nDocuments stored with embeddings contain:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `title` | string | Document title |\n| `content` | string | Original text content |\n| `extension` | string | File extension/type |\n| `labels` | list | User-defined labels |\n| `source` | string | Source URL or reference |\n| `fileSize` | int | Size in bytes |\n| `metadata` | dict | Additional metadata |\n| `vectors` | array | Embedding vectors |\n\n资料来源：[goldenverba/components/document.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/document.py)\n\n## Dependency Management\n\nCore embedding dependencies are specified in `setup.py`:\n\n```python\ninstall_requires=[\n    \"weaviate-client==4.9.6\",\n    \"openpyxl==3.1.5\",\n    \"fastapi==0.111.1\",\n    # ... additional dependencies\n]\n```\n\n资料来源：[setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n\n## Deployment Considerations\n\n### Local Deployment\n\nWhen running Verba locally, users can select embedders that don't require API keys (such as SentenceTransformers) or configure API-based embedders with appropriate keys.\n\n### Production Deployment\n\nIn production environments:\n\n- Embedder selection may be restricted based on deployment type\n- API keys should be configured via environment variables\n- Vector storage is managed through the configured Weaviate instance\n\n## Summary\n\nVerba's embedding and vector storage system provides a flexible, provider-agnostic approach to semantic search. By supporting multiple embedding providers and integrating with Weaviate for vector storage, the system enables effective retrieval-augmented generation across various use cases. Configuration can be done per-document or at the system level, giving users fine-grained control over the RAG pipeline.\n\n---\n\n<a id='page-retrieval-system'></a>\n\n## RAG Retrieval System\n\n### 相关页面\n\n相关主题：[Embedding and Vector Storage](#page-embedding-system), [LLM Generators and Answer Generation](#page-llm-generators)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [goldenverba/components/document.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/document.py)\n- [goldenverba/components/retriever/WindowRetriever.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/retriever/WindowRetriever.py)\n- [goldenverba/components/retriever/__init__.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/retriever/__init__.py)\n- [goldenverba/verba_manager.py](https://github.com/weaviate/Verba/blob/main/goldenverba/verba_manager.py)\n- [frontend/app/components/Document/DocumentExplorer.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Document/DocumentExplorer.tsx)\n- [frontend/app/components/Document/VectorView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Document/VectorView.tsx)\n- [frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n- [frontend/app/components/Chat/ChatConfig.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatConfig.tsx)\n</details>\n\n# RAG Retrieval System\n\n## Overview\n\nThe RAG (Retrieval-Augmented Generation) Retrieval System is the core query mechanism in Verba that enables semantic search across document collections. It retrieves relevant text chunks from vectorized documents stored in Weaviate and delivers them to the Generator component for answer synthesis.\n\nIn Verba's architecture, the Retrieval System operates as a pipeline component that:\n\n1. Receives user queries from the frontend chat interface\n2. Embeds the query using the configured Embedder\n3. Performs vector similarity search in Weaviate\n4. Returns ranked chunks to the chat interface for display and generation\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx](frontend/app/components/Chat/ChatConfig.tsx)\n\n---\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n    A[User Query] --> B[Frontend ChatInterface]\n    B --> C[ChatConfig - Retriever Selection]\n    C --> D[WindowRetriever]\n    D --> E[Weaviate Vector Database]\n    D --> F[Embedder Service]\n    F --> E\n    E --> G[Retrieved Chunks]\n    G --> B\n    G --> H[Generator - Answer Synthesis]\n```\n\n### Component Pipeline\n\nThe RAG pipeline in Verba follows a modular architecture where each component can be swapped via configuration:\n\n| Component | Role | Location |\n|-----------|------|----------|\n| **Embedder** | Converts query text to vector embedding | `goldenverba/components/embedder/` |\n| **Retriever** | Performs similarity search | `goldenverba/components/retriever/` |\n| **Generator** | Synthesizes answer from retrieved chunks | `goldenverba/components/generator/` |\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:35-48](frontend/app/components/Chat/ChatConfig.tsx)\n\n---\n\n## Retriever Components\n\n### WindowRetriever\n\nThe `WindowRetriever` is the primary retriever implementation that performs vector similarity search with configurable parameters.\n\n**File:** `goldenverba/components/retriever/WindowRetriever.py`\n\n**Configuration Options:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `window_distance` | int | 3 | Number of chunks to include around the matched chunk |\n| `max_chunks` | int | 10 | Maximum number of chunks to retrieve per query |\n| `min_score` | float | 0.0 | Minimum similarity score threshold |\n\n### Retriever Base Class\n\nAll retrievers inherit from the base `Retriever` class which defines the standard interface:\n\n```python\nclass Retriever:\n    def __init__(self, config: Config, embedder: Embedder):\n        \"\"\"Initialize retriever with config and embedder.\"\"\"\n        \n    def retrieve(self, query: str, limit: int = 10) -> list[Chunk]:\n        \"\"\"Retrieve relevant chunks for a query.\"\"\"\n        \n    def get_name(self) -> str:\n        \"\"\"Return the retriever name.\"\"\"\n```\n\n资料来源：[goldenverba/components/retriever/__init__.py](goldenverba/components/retriever/__init__.py)\n\n---\n\n## Data Models\n\n### Document Structure\n\nDocuments are the primary data unit in Verba's retrieval system:\n\n```python\nclass Document:\n    title: str\n    content: str\n    extension: str\n    labels: list[str]\n    source: str\n    fileSize: str\n    metadata: str\n    meta: dict\n```\n\n资料来源：[goldenverba/components/document.py:1-30](goldenverba/components/document.py)\n\n### Document Creation\n\nDocuments are created from file content using `FileConfig`:\n\n```python\ndef create_document(content: str, fileConfig: FileConfig) -> Document:\n    return Document(\n        title=fileConfig.filename,\n        content=content,\n        extension=fileConfig.extension,\n        labels=fileConfig.labels,\n        source=fileConfig.source,\n        fileSize=fileConfig.file_size,\n        metadata=fileConfig.metadata,\n        meta={},\n    )\n```\n\n资料来源：[goldenverba/components/document.py:32-45](goldenverba/components/document.py)\n\n---\n\n## Frontend Integration\n\n### Document Explorer\n\nThe `DocumentExplorer` component provides a UI for browsing and searching documents:\n\n**Features:**\n- Document search with filtering by labels\n- Metadata display (file size, source URL, labels)\n- Vector visualization access\n- Document deletion functionality\n\n**File:** `frontend/app/components/Document/DocumentExplorer.tsx`\n\n```tsx\ninterface Document {\n  id: string;\n  title: string;\n  content: string;\n  fileSize: string;\n  source: string;\n  labels: string[];\n  vectors: Vector[];\n}\n```\n\n### Vector View\n\nThe `VectorView` component visualizes document vectors in the Weaviate database:\n\n```tsx\ninterface VectorData {\n  collection_name: string;\n  vectors: Vector[];\n}\n```\n\n资料来源：[frontend/app/components/Document/VectorView.tsx](frontend/app/components/Document/VectorView.tsx)\n\n---\n\n## Query Flow\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Frontend\n    participant ChatInterface\n    participant Retriever\n    participant Weaviate\n    participant Generator\n\n    User->>Frontend: Enter query\n    Frontend->>ChatInterface: Send message\n    ChatInterface->>Retriever: retrieve(query)\n    Retriever->>Retriever: embed_query(query)\n    Retriever->>Weaviate: nearVector search\n    Weaviate->>Retriever: ranked chunks\n    Retriever->>ChatInterface: return chunks\n    ChatInterface->>Frontend: display chunks\n    ChatInterface->>Generator: generate(chunks, query)\n    Generator->>User: response\n```\n\n---\n\n## Configuration\n\n### Retriever Selection in Chat Config\n\nThe Chat Config UI allows users to select and configure retrievers:\n\n```tsx\n<ComponentView\n    RAGConfig={RAGConfig}\n    component_name=\"Retriever\"\n    selectComponent={selectComponent}\n    updateConfig={updateConfig}\n    saveComponentConfig={saveComponentConfig}\n    blocked={production == \"Demo\"}\n/>\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:40-46](frontend/app/components/Chat/ChatConfig.tsx)\n\n### Production Modes\n\n| Mode | Retrieval | Description |\n|------|-----------|-------------|\n| `Demo` | Disabled | Read-only demo with pre-loaded data |\n| `Local` | Full Access | Local Weaviate + Ollama setup |\n| `Production` | Full Access | External Weaviate Cloud |\n\n---\n\n## Verba Manager Integration\n\nThe `VerbaManager` orchestrates all RAG components including retrieval:\n\n**Key Responsibilities:**\n- Initialize and manage component lifecycle\n- Route queries through the RAG pipeline\n- Manage Weaviate connections\n- Handle configuration persistence\n\n资料来源：[goldenverba/verba_manager.py](goldenverba/verba_manager.py)\n\n---\n\n## Summary\n\nThe RAG Retrieval System in Verba provides a flexible, modular mechanism for semantic search across vectorized documents:\n\n| Aspect | Implementation |\n|--------|----------------|\n| **Retrieval Method** | Vector similarity search via Weaviate |\n| **Primary Retriever** | WindowRetriever with configurable window distance |\n| **Query Flow** | Embed → Search → Rank → Return |\n| **Frontend Access** | ChatInterface with chunk display |\n| **Configuration** | Per-deployment RAGConfig with swap-able components |\n\nThis architecture allows users to customize each stage of the retrieval pipeline according to their specific use case requirements.\n\n---\n\n<a id='page-llm-generators'></a>\n\n## LLM Generators and Answer Generation\n\n### 相关页面\n\n相关主题：[LLM Generators and Answer Generation](#page-llm-generators), [RAG Retrieval System](#page-retrieval-system)\n\n<details>\n<summary>Related Source Files</summary>\n\n以下源码文件用于生成本页说明：\n\n- [goldenverba/components/generation/OpenAIGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/OpenAIGenerator.py)\n- [goldenverba/components/generation/AnthrophicGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/AnthrophicGenerator.py)\n- [goldenverba/components/generation/CohereGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/CohereGenerator.py)\n- [goldenverba/components/generation/GroqGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/GroqGenerator.py)\n- [goldenverba/components/generation/OllamaGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/OllamaGenerator.py)\n- [goldenverba/components/generation/GeminiGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/GeminiGenerator.py)\n- [goldenverba/components/generation/NovitaGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/NovitaGenerator.py)\n- [goldenverba/components/generation/UpstageGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/UpstageGenerator.py)\n- [goldenverba/components/generation/AtlasCloudGenerator.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/generation/AtlasCloudGenerator.py)\n</details>\n\n# LLM Generators and Answer Generation\n\n## Overview\n\nVerba implements a modular LLM Generator system that provides answer generation capabilities for the RAG (Retrieval-Augmented Generation) pipeline. The system supports multiple LLM providers through a common interface abstraction, allowing users to choose their preferred generation backend while maintaining consistent behavior across the application.\n\nThe generation module is part of Verba's component architecture, where each generator implements a common interface that defines methods for retrieving supported models, generating responses, and managing authentication credentials.\n\n## Architecture\n\n### Generator Interface\n\nAll LLM generators in Verba inherit from a common base class that defines the contract for generation operations. This design enables:\n\n- **Provider Agnosticism**: Switch between LLM providers without changing application code\n- **Consistent API**: All generators expose the same methods for model listing and text generation\n- **Credential Management**: Unified handling of API keys and authentication\n\n### Supported Providers\n\nVerba supports the following LLM providers for answer generation:\n\n| Provider | Class Name | API Type | Cloud/Local |\n|----------|------------|----------|-------------|\n| OpenAI | `OpenAIGenerator` | REST API | Cloud |\n| Anthropic | `AnthrophicGenerator` | REST API | Cloud |\n| Cohere | `CohereGenerator` | REST API | Cloud |\n| Groq | `GroqGenerator` | REST API | Cloud |\n| Ollama | `OllamaGenerator` | Local API | Local |\n| Gemini | `GeminiGenerator` | REST API | Cloud |\n| Novita AI | `NovitaGenerator` | REST API | Cloud |\n| Upstage | `UpstageGenerator` | REST API | Cloud |\n| Atlas Cloud | `AtlasCloudGenerator` | REST API | Cloud |\n\n## Generation Workflow\n\n```mermaid\ngraph TD\n    A[User Query] --> B[RAG Pipeline]\n    B --> C[Retrieval: Find Relevant Chunks]\n    C --> D[Context Assembly]\n    D --> E[LLM Generator]\n    E --> F[Prompt Construction]\n    F --> G[API Call to LLM Provider]\n    G --> H[Response Parsing]\n    H --> I[Formatted Answer]\n    \n    J[Credentials] --> E\n    K[System Prompt] --> F\n    L[Model Selection] --> G\n```\n\n## Configuration\n\n### Environment Variables\n\nGeneration behavior can be configured through environment variables:\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `OLLAMA_MODEL` | Default Ollama model for local generation | For Ollama setup |\n| `OLLAMA_EMBED_MODEL` | Default Ollama embedding model | For Ollama setup |\n| `OPENAI_API_KEY` | API key for OpenAI provider | For OpenAI setup |\n| `ANTHROPIC_API_KEY` | API key for Anthropic/Claude | For Anthropic setup |\n\n### Runtime Configuration\n\nThe frontend allows dynamic model selection through the `ChatConfig` component. When users select a deployment type, Verba fetches available models from the configured provider and presents them in the UI.\n\nFrom `frontend/app/components/Chat/ChatInterface.tsx`:\n```typescript\n<ChatConfig\n  addStatusMessage={addStatusMessage}\n  production={production}\n  RAGConfig={RAGConfig}\n  credentials={credentials}\n  setRAGConfig={setRAGConfig}\n  onReset={onResetConfig}\n  onSave={onSaveConfig}\n/>\n```\n\n## Component Interaction\n\n### Chat Pipeline\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Frontend\n    participant Backend\n    participant Generator\n    participant LLM_Provider\n    \n    User->>Frontend: Submit Query\n    Frontend->>Backend: /api/chat with query\n    Backend->>Generator: Generate response\n    Generator->>LLM_Provider: API request\n    LLM_Provider-->>Generator: LLM Response\n    Generator-->>Backend: Formatted answer\n    Backend-->>Frontend: Stream response\n    Frontend->>User: Display answer\n```\n\n### Message Handling\n\nThe chat interface manages different fetching states during generation:\n\n```typescript\n{fetchingStatus === \"CHUNKS\" && \"Retrieving...\"}\n{fetchingStatus === \"RESPONSE\" && \"Generating...\"}\n```\n\nUsers can cancel ongoing generation through the UI, which sets the fetching status to `DONE` and stops further API calls.\n\n## Document-to-Answer Flow\n\nWhen processing documents for RAG:\n\n1. **Ingestion**: Documents are parsed and chunked via Reader components\n2. **Storage**: Chunks are embedded and stored in Weaviate\n3. **Retrieval**: Relevant chunks are fetched based on query similarity\n4. **Generation**: Selected chunks are sent to the LLM generator with the user's query\n\nFrom `goldenverba/components/document.py`:\n```python\ndef create_document(content: str, fileConfig: FileConfig) -> Document:\n    \"\"\"Create a Document object from the file content.\"\"\"\n    return Document(\n        title=fileConfig.filename,\n        content=content,\n        extension=fileConfig.extension,\n        labels=fileConfig.labels,\n        source=fileConfig.source,\n        fileSize=fileConfig.file_size,\n        metadata=fileConfig.metadata,\n        meta={},\n    )\n```\n\n## Deployment Types\n\nVerba supports different deployment configurations that affect generation behavior:\n\n| Deployment | Description | Generator Usage |\n|------------|-------------|-----------------|\n| Weaviate Cloud | Full cloud deployment | Cloud-based LLM APIs |\n| Docker | Containerized deployment | Configurable via environment |\n| Local | Development setup | Often uses Ollama |\n| Custom | User-defined infrastructure | Flexible configuration |\n\nThe deployment type is selected during the initial setup through the `LoginView` component:\n\nFrom `frontend/app/components/Login/LoginView.tsx`:\n```typescript\n{production == \"Local\" && (\n    <div className=\"flex flex-col justify-start gap-2 w-full\">\n        <VerbaButton\n            Icon={FaDatabase}\n            title=\"Weaviate\"\n            onClick={() => setSelectedDeployment(\"Weaviate\")}\n        />\n        {/* Docker, Custom, Local options */}\n    </div>\n)}\n```\n\n## Model Selection\n\n### Dynamic Model Retrieval\n\nVerba supports dynamic model name retrieval for OpenAI-compatible APIs based on the provided API key and URL. This allows the system to automatically discover and list available models from the configured provider.\n\nFrom `CHANGELOG.md`:\n> Dynamic model name retrieval for OpenAI Generator based on OpenAI URL and API Key\n\n### Model Fallback\n\nWhen automatic model detection is unavailable, Verba uses default models:\n- **OpenAI**: `gpt-4o-mini`\n- **Anthropic**: `claude-3-haiku-20240307`\n- **Ollama**: Configurable via `OLLAMA_MODEL`\n\n## Status and Error Handling\n\nThe application uses a status messenger system to communicate generation states to users:\n\n```typescript\n{messages.filter((message) => {\n    const messageTime = new Date(message.timestamp).getTime();\n    const currentTime = new Date().getTime();\n    return currentTime - messageTime < 5000; // 5 seconds\n}).map((message, index) => (\n    <motion.div key={index}>\n        {/* Status message display */}\n    </motion.div>\n))}\n```\n\nMessages are categorized by type and automatically expire after 5 seconds.\n\n## Reset Capabilities\n\nThe Settings panel (`InfoView`) provides reset functionality that affects generation:\n\n| Action | Scope | Effect on Generation |\n|--------|-------|----------------------|\n| Reset Documents | Data | Clears chunks, requires re-retrieval |\n| Reset Config | Configuration | Resets model selection and prompts |\n| Reset Verba | All Data | Full system reset including models |\n| Reset Suggestions | Autocomplete | Clears cached suggestions |\n\nFrom `frontend/app/components/Settings/InfoView.tsx`:\n```typescript\n<UserModalComponent\n    modal_id=\"reset-documents\"\n    title=\"Reset Documents\"\n    text=\"Are you sure you want to reset all documents?\"\n    triggerAccept={resetDocuments}\n    triggerString=\"Reset\"\n/>\n```\n\n## Dependencies\n\nThe generation module relies on the following core dependencies:\n\nFrom `setup.py`:\n```python\ninstall_requires=[\n    \"weaviate-client==4.9.6\",\n    \"fastapi==0.111.1\",\n    \"uvicorn[standard]==0.29.0\",\n    \"click==8.1.7\",\n    # Provider-specific SDKs loaded dynamically\n]\n```\n\n## Version History\n\n| Version | Changes |\n|---------|---------|\n| 2.1.3 | Added `OLLAMA_MODEL` and `OLLAMA_EMBED_MODEL` environment variables |\n| 2.1.2 | Added Novita Generator |\n| 2.1.1 | Dynamic model retrieval for OpenAI Generator |\n| 2.1.0 | Added Upstage Generator, Groq, improved configuration |\n\n## Best Practices\n\n1. **API Key Security**: Store API keys in `.env` files rather than hardcoding\n2. **Model Selection**: Choose models based on task requirements (speed vs. quality)\n3. **Chunk Configuration**: Adjust chunk sizes to match model's context window\n4. **Rate Limits**: Be aware of provider-specific rate limits for high-volume usage\n\n## See Also\n\n- [Retrieval System](docs/retrieval.md)\n- [Embedders and Vectorization](docs/embedders.md)\n- [Document Ingestion Pipeline](docs/ingestion.md)\n- [Deployment Guide](docs/deployment.md)\n\n---\n\n<a id='page-embedders'></a>\n\n## Embedder Configuration\n\n### 相关页面\n\n相关主题：[Embedding and Vector Storage](#page-embedding-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n- [frontend/app/components/Chat/ChatConfig.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatConfig.tsx)\n- [frontend/app/components/Ingestion/ComponentView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/ComponentView.tsx)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n</details>\n\n# Embedder Configuration\n\n## Overview\n\nThe Embedder is a core component in Verba's RAG (Retrieval-Augmented Generation) pipeline responsible for converting text content into vector embeddings. These embeddings enable semantic search capabilities by representing documents and queries as numerical vectors in a high-dimensional space.\n\nVerba supports multiple embedder implementations including OpenAI, Ollama, Upstage, and other providers. The embedder configuration system allows users to select their preferred embedding provider, configure provider-specific settings, and integrate with the broader RAG pipeline.\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:24-35]()\n\n## Architecture\n\n### RAG Pipeline Integration\n\nThe Embedder operates as part of a modular RAG configuration system alongside the Retriever and Generator components.\n\n```mermaid\ngraph TD\n    A[Document Input] --> B[Reader]\n    B --> C[Chunker]\n    C --> D[Embedder]\n    D --> E[Weaviate Vector Store]\n    F[User Query] --> G[Embedder]\n    G --> H[Retriever]\n    H --> I[Generator]\n    I --> J[Response]\n    E -.-> H\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:24-35]()\n\n### Component Selection Flow\n\nUsers interact with the embedder configuration through a component selection interface:\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant ComponentView\n    participant RAGConfig\n    participant Embedder\n    \n    User->>ComponentView: Select Embedder Component\n    ComponentView->>RAGConfig: updateConfig(Embedder, selection)\n    RAGConfig->>Embedder: Apply Configuration\n    Embedder-->>RAGConfig: Confirm Settings\n    RAGConfig-->>ComponentView: Update UI\n    ComponentView-->>User: Display Updated State\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-100]()\n\n## Configuration UI\n\n### Embedder Selection Panel\n\nThe embedder can be configured through the ingestion interface where users select and customize embedding models for their documents.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `selected` | string | Currently selected embedder name |\n| `components` | object | Available embedder implementations |\n| `description` | string | Human-readable description of selected embedder |\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:85-95]()\n\n### Display and Configuration\n\nThe UI displays the currently selected embedder with its configuration:\n\n```tsx\n<div className=\"flex gap-2 justify-between items-center text-text-verba\">\n  <p className=\"flex min-w-[8vw]\">Embedder</p>\n  <label className=\"input flex items-center gap-2 w-full bg-bg-verba\">\n    <input\n      type=\"text\"\n      className=\"grow w-full\"\n      value={fileMap[selectedFileData].rag_config[\"Embedder\"].selected}\n      disabled={true}\n    />\n  </label>\n</div>\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:85-95]()\n\n### Dynamic Description\n\nEach embedder component provides a description that is displayed in the UI:\n\n```tsx\n<div className=\"flex gap-2 items-center text-text-verba\">\n  <p className=\"flex min-w-[8vw]\"></p>\n  <p className=\"text-sm text-text-alt-verba text-start\">\n    {selectedFileData &&\n      fileMap[selectedFileData].rag_config[\"Embedder\"].components[\n        fileMap[selectedFileData].rag_config[\"Embedder\"].selected\n      ].description}\n  </p>\n</div>\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:97-106]()\n\n## RAG Configuration System\n\n### Configuration Structure\n\nThe embedder is configured within the `RAGConfig` object which manages all pipeline components:\n\n```typescript\ninterface RAGConfig {\n  Embedder: {\n    selected: string;\n    components: Record<string, EmbedderComponent>;\n  };\n  Generator: {\n    selected: string;\n    components: Record<string, GeneratorComponent>;\n  };\n  Retriever: {\n    selected: string;\n    components: Record<string, RetrieverComponent>;\n  };\n}\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:1-50]()\n\n### Component View Integration\n\nThe `ComponentView` component renders the embedder selection UI:\n\n```tsx\n<ComponentView\n  RAGConfig={RAGConfig}\n  component_name=\"Embedder\"\n  selectComponent={selectComponent}\n  updateConfig={updateConfig}\n  saveComponentConfig={saveComponentConfig}\n  blocked={production == \"Demo\"}\n/>\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:24-35]()\n\n## Supported Embedder Providers\n\n### Provider Matrix\n\n| Provider | Environment Variables | Version Added | Features |\n|----------|----------------------|---------------|----------|\n| OpenAI | `OPENAI_API_KEY`, `OPENAI_URL` | Base | Dynamic model name retrieval |\n| Ollama | `OLLAMA_EMBED_MODEL` | 2.1.3 | Local embedding models |\n| Upstage | (Upstage-specific) | 2.1.0 | High-performance embeddings |\n\n资料来源：[CHANGELOG.md:1-30](), [setup.py:1-50]()\n\n### Environment Variables\n\nVerba supports environment variables for embedder configuration:\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `OLLAMA_EMBED_MODEL` | Ollama embedding model name | `nomic-embed-text` |\n| `OPENAI_API_KEY` | OpenAI API key | `sk-...` |\n| `OPENAI_URL` | OpenAI API endpoint | `https://api.openai.com/v1` |\n\n资料来源：[CHANGELOG.md:1-15]()\n\n## Deployment Modes\n\n### Demo Mode Restrictions\n\nIn Demo mode, the embedder configuration is locked to prevent changes:\n\n```tsx\nblocked={production == \"Demo\"}\n```\n\nThis ensures that demo deployments maintain consistent behavior and don't allow users to modify the embedding pipeline.\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:24-35]()\n\n### Configuration Persistence\n\nThe embedder configuration is saved through the `saveComponentConfig` callback:\n\n```tsx\n<ComponentView\n  RAGConfig={RAGConfig}\n  component_name=\"Embedder\"\n  selectComponent={selectComponent}\n  updateConfig={updateConfig}\n  saveComponentConfig={saveComponentConfig}\n  blocked={production == \"Demo\"}\n/>\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:24-35]()\n\n## Debugging Embedder Configuration\n\n### Debug Modal\n\nVerba provides a debug view for inspecting file configuration including embedder settings:\n\n```tsx\n<VerbaButton\n  Icon={CgDebug}\n  onClick={openDebugModal}\n  className=\"max-w-min\"\n/>\n\n<dialog id={\"File_Debug_Modal\"} className=\"modal\">\n  <pre className=\"whitespace-pre-wrap text-xs\">\n    {selectedFileData\n      ? (() => {\n          const objCopy = { ...fileMap[selectedFileData] };\n          objCopy.content = \"File Content\";\n          return JSON.stringify(objCopy, null, 2);\n        })()\n      : \"\"}\n  </pre>\n</dialog>\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:110-130]()\n\n## File-Level Configuration\n\n### Per-File Embedder Override\n\nEach file can have its own embedder configuration that overrides the global RAG config:\n\n```typescript\ninterface FileConfig {\n  filename: string;\n  extension: string;\n  labels: string[];\n  source: string;\n  file_size: number;\n  metadata: Record<string, any>;\n  rag_config: RAGConfig;\n}\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-100]()\n\n### Accessing File Embedder Config\n\n```typescript\nfileMap[selectedFileData].rag_config[\"Embedder\"].selected\nfileMap[selectedFileData].rag_config[\"Embedder\"].components\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:85-106]()\n\n## Version History\n\n| Version | Changes |\n|---------|---------|\n| 2.1.3 | Added `OLLAMA_MODEL` and `OLLAMA_EMBED_MODEL` environment variables |\n| 2.1.0 | Added Upstage Embedder support |\n| 2.1.1 | Dynamic model name retrieval for OpenAI |\n\n资料来源：[CHANGELOG.md:1-30]()\n\n## Dependencies\n\nVerba requires the Weaviate client for vector storage operations:\n\n```python\ninstall_requires=[\n    \"weaviate-client==4.9.6\",\n    \"python-dotenv==1.0.0\",\n    \"openpyxl==3.1.5\",\n    \"wasabi==1.1.2\",\n    \"fastapi==0.111.1\",\n    \"uvicorn[standard]==0.29.0\",\n    \"gunicorn==22.0.0\",\n    \"click==8.1.7\",\n]\n```\n\n资料来源：[setup.py:15-25]()\n\n## Best Practices\n\n1. **Use Environment Variables**: Store API keys and model names in `.env` files rather than hardcoding\n2. **Test in Non-Demo Mode**: Full configuration features require non-Demo deployment\n3. **Leverage Debug Mode**: Use the debug modal to inspect configuration state\n4. **Check Provider Support**: Ensure your chosen embedder provider is compatible with your deployment mode\n\n---\n\n<a id='page-frontend-components'></a>\n\n## Frontend Component Overview\n\n<details>\n<summary>Related Source Files</summary>\n\nThe following source files were used to generate this documentation:\n\n- [frontend/app/page.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/page.tsx)\n- [frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n- [frontend/app/components/Chat/ChatMessage.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatMessage.tsx)\n- [frontend/app/components/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n- [frontend/app/components/Navigation/StatusMessenger.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/StatusMessenger.tsx)\n- [frontend/app/components/Document/ContentView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Document/ContentView.tsx)\n- [frontend/app/components/Settings/InfoView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Settings/InfoView.tsx)\n- [frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n- [frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n- [frontend/app/components/Ingestion/FileSelectionView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/FileSelectionView.tsx)\n</details>\n\n# Frontend Component Overview\n\n## Introduction\n\nThe Verba frontend is a React-based web application that provides a user-friendly interface for Retrieval-Augmented Generation (RAG) operations. Built with Next.js and TypeScript, the frontend enables users to interact with their data through chat interfaces, document management, and configuration settings.\n\n资料来源：[frontend/app/page.tsx:1-50]()\n\n## Architecture Overview\n\nThe frontend follows a modular component-based architecture organized by functionality. The application uses WebSocket connections for real-time communication with the backend server, enabling live status updates and streaming responses.\n\n```mermaid\ngraph TD\n    A[App Entry Point] --> B[LoginView]\n    A --> C[Main Application]\n    C --> D[NavbarComponent]\n    C --> E[ChatInterface]\n    C --> F[Document Components]\n    C --> G[Ingestion Components]\n    C --> H[Settings Components]\n    D --> I[StatusMessenger]\n    E --> J[ChatMessage]\n    E --> K[ChatConfig]\n```\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:1-100]()\n\n## Core Components\n\n### Navigation Components\n\n#### NavbarComponent\n\nThe navigation bar serves as the primary routing mechanism within the application. It displays different pages based on the user's current selection and deployment mode.\n\n| Prop | Type | Description |\n|------|------|-------------|\n| `currentPage` | `string` | Current active page identifier |\n| `setCurrentPage` | `function` | Callback to change active page |\n| `production` | `string` | Deployment type (Local, Demo, Docker, etc.) |\n| `gitHubStars` | `string` | GitHub star count display |\n\nThe NavbarComponent conditionally renders menu items based on the `production` environment. In non-Demo modes, additional options like \"Import Data\" and \"Settings\" become available.\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:1-150]()\n\n#### StatusMessengerComponent\n\nThe StatusMessengerComponent provides toast-style notifications for application events. Messages are filtered to display only those within the last 5 seconds, providing transient user feedback.\n\n```mermaid\ngraph LR\n    A[Message Event] --> B[Timestamp Check]\n    B --> C{Within 5s?}\n    C -->|Yes| D[Animate In]\n    C -->|No| E[Filter Out]\n    D --> F[Display Message]\n    F --> G[Animate Out]\n```\n\nMessages are color-coded by type using a `getMessageColor()` function and include icons for visual identification.\n\n资料来源：[frontend/app/components/Navigation/StatusMessenger.tsx:1-80]()\n\n### Chat Components\n\n#### ChatInterface\n\nThe ChatInterface is the central component for RAG interactions. It manages chat messages, user input, and the configuration panel.\n\n| State Variable | Type | Purpose |\n|---------------|------|---------|\n| `messages` | `Message[]` | Array of chat messages |\n| `previewText` | `string` | Streaming response preview |\n| `isFetching` | `RefObject` | Fetching status indicator |\n| `selectedSetting` | `string` | Active sub-panel (Chat/Config) |\n| `fetchingStatus` | `string` | Current operation status |\n\nThe component supports two sub-views: the chat view for conversation and a configuration view for RAG settings. A cancel button allows users to interrupt ongoing operations.\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:1-150]()\n\n#### ChatMessage\n\nThe ChatMessage component renders individual messages with support for multiple message types and syntax highlighting for code blocks.\n\n| Message Type | Styling | Features |\n|-------------|---------|----------|\n| `user` | Right-aligned, primary background | Plain text display |\n| `system` | Left-aligned, alternate background | Markdown + syntax highlighting |\n| `error` | Warning background color | Error notifications |\n| `retrieval` | Standard background | Retrieval results |\n\nFor system messages containing code, the component uses `react-syntax-highlighter` with theme support for both light and dark modes.\n\n```tsx\n<SyntaxHighlighter\n  style={selectedTheme.theme === \"dark\" ? oneDark : oneLight}\n  language={match[1]}\n  PreTag=\"div\"\n>\n  {String(children).replace(/\\n$/, \"\")}\n</SyntaxHighlighter>\n```\n\n资料来源：[frontend/app/components/Chat/ChatMessage.tsx:1-100]()\n\n### Document Components\n\n#### ContentView\n\nThe ContentView component displays document content with pagination support for both chunks and pages.\n\n| Feature | Description |\n|---------|-------------|\n| Chunk Navigation | Previous/Next chunk buttons |\n| Page Navigation | Page-based content display |\n| Scroll Handling | Overflow auto-scroll for long content |\n| Label Display | Truncated label badges with max-width constraints |\n\nThe component conditionally renders navigation text based on whether chunk scores are available, switching between \"Chunk\" and \"Page\" labels.\n\n资料来源：[frontend/app/components/Document/ContentView.tsx:1-100]()\n\n### Ingestion Components\n\n#### BasicSettingView\n\nThe BasicSettingView provides configuration options for document ingestion, including source links and labels.\n\n| Field | Purpose | Constraints |\n|-------|---------|-------------|\n| `source` | Reference link to original document | Optional field |\n| `label` | Document categorization labels | Enter key adds label |\n| `chunker` | Text chunking strategy | Read-only display |\n| `embedder` | Embedding model selection | Read-only display |\n\nLabels are added via keyboard (Enter key) or button click, with each label rendered as a removable badge.\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-150]()\n\n#### FileSelectionView\n\nThe FileSelectionView displays a list of selected files and provides import functionality.\n\nFiles are rendered as `FileComponent` instances, each with delete and selection capabilities. The import footer contains action buttons that become available when the WebSocket connection is online.\n\n```mermaid\ngraph TD\n    A[FileSelectionView] --> B[FileComponent List]\n    B --> C{User Action}\n    C --> D[Delete File]\n    C --> E[Select File]\n    C --> F[Import Selected]\n    F --> G{WebSocket Online?}\n    G -->|Yes| H[Show Import Button]\n    G -->|No| I[Hide Import Button]\n```\n\n资料来源：[frontend/app/components/Ingestion/FileSelectionView.tsx:1-100]()\n\n### Settings Components\n\n#### InfoView\n\nThe InfoView component displays system information and provides reset functionality for various aspects of the application.\n\n| Section | Information Displayed |\n|---------|----------------------|\n| Weaviate Cluster | Name, status, shard count |\n| Collections | Collection count, names, object counts |\n| Reset Options | Documents, Config, Verba, Suggestions |\n\nReset operations are protected by modal confirmations using the `UserModalComponent`, requiring explicit user confirmation before executing destructive actions.\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:1-100]()\n\n### Login Components\n\n#### LoginView\n\nThe LoginView handles initial deployment type selection for the application.\n\n| Deployment Option | Icon | Description |\n|------------------|------|-------------|\n| Weaviate | `FaDatabase` | Weaviate Cloud deployment |\n| Docker | `FaDocker` | Docker container deployment |\n| Custom | `TbDatabaseEdit` | Custom backend connection |\n| Local | `FaLaptopCode` | Local development mode |\n\nThe component manages connection states and displays loading indicators during authentication attempts.\n\n资料来源：[frontend/app/components/Login/LoginView.tsx:1-100]()\n\n## Application Entry Point\n\nThe main page component (`frontend/app/page.tsx`) orchestrates the overall application flow, handling:\n\n- Environment detection and configuration\n- WebSocket connection management\n- Theme persistence\n- Page routing based on deployment status\n\n```mermaid\ngraph TD\n    A[Page Load] --> B{Production Mode?}\n    B -->|Demo| C[Direct to Main]\n    B -->|Local| D[LoginView]\n    D --> E{Deployment Selected}\n    E -->|Weaviate| F[Configure Weaviate]\n    E -->|Docker| G[Connect to Docker]\n    E -->|Custom| H[Configure Custom]\n    E -->|Local| I[Full Setup]\n    F --> J[Main Application]\n    G --> J\n    H --> J\n    I --> J\n    C --> J\n```\n\nThe footer displays a \"Built with ♥ and Weaviate\" message, confirming the project's association with Weaviate.\n\n资料来源：[frontend/app/page.tsx:1-80]()\n\n## Theme System\n\nThe application supports both light and dark themes, with theme preferences persisted across sessions. Theme values are passed down to components that require styling adjustments, such as `ChatMessage` for syntax highlighting.\n\n```tsx\n// Theme-dependent syntax highlighting\nconst codeStyle = selectedTheme.theme === \"dark\" ? oneDark : oneLight;\n```\n\n## Component Communication\n\nComponents communicate through several mechanisms:\n\n1. **Props Drilling**: Parent components pass state and callbacks to children via props\n2. **Ref Objects**: Used for mutable values that don't trigger re-renders (e.g., `isFetching`)\n3. **WebSocket Events**: Real-time updates from the backend server\n4. **State Callbacks**: Functions like `setCurrentPage` for navigation state\n\n## State Management Summary\n\n| Component Area | Primary State | Secondary State |\n|---------------|---------------|-----------------|\n| Chat | `messages`, `previewText` | `fetchingStatus`, `selectedSetting` |\n| Documents | `content`, `chunkScores` | `page`, `selectedDocument` |\n| Ingestion | `fileMap`, `selectedFileData` | `source`, `label` |\n| Navigation | `currentPage` | `socketOnline`, `production` |\n| Settings | `collectionPayload` | `clusterPayload`, `credentials` |\n\n## Styling Conventions\n\nThe frontend uses Tailwind CSS with custom color variables following the `-verba` suffix convention:\n\n| Color Variable | Usage |\n|---------------|-------|\n| `bg-bg-verba` | Primary background |\n| `bg-bg-alt-verba` | Alternate background |\n| `text-text-verba` | Primary text |\n| `text-text-alt-verba` | Alternate text |\n| `bg-button-verba` | Button backgrounds |\n| `hover:bg-button-hover-verba` | Button hover states |\n\nThis systematic naming ensures consistent theming throughout the application.\n\n## Key Features Summary\n\n| Feature | Components | Description |\n|---------|------------|-------------|\n| Chat Interface | ChatInterface, ChatMessage | RAG conversation with syntax highlighting |\n| Document Explorer | ContentView, DocumentExplorer | View and navigate documents/chunks |\n| Data Import | FileSelectionView, BasicSettingView | File upload and configuration |\n| System Settings | InfoView, SettingsView | System info and reset options |\n| Real-time Updates | StatusMessenger | Toast notifications for events |\n| Navigation | NavbarComponent | Page routing and menu |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：weaviate/Verba\n\n摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：1.0.1 Beautiful Verba。\n\n## 1. 安装坑 · 来源证据：1.0.1 Beautiful Verba\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.0.1 Beautiful Verba\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b08b22b1d7404da6ae9d8153c53602cd | https://github.com/weaviate/Verba/releases/tag/1.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：v0.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.4.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_199393ab54bc4fd79d576c42dc3198f2 | https://github.com/weaviate/Verba/releases/tag/0.4.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v1.0.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_90c577983a844f3ba246a181a8e03997 | https://github.com/weaviate/Verba/releases/tag/v1.0.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：v2.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0ec01ecbe8494b08a039e08f6bf68f01 | https://github.com/weaviate/Verba/releases/tag/v2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:672002598 | https://github.com/weaviate/Verba | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | last_activity_observed missing\n\n## 7. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:672002598 | https://github.com/weaviate/Verba | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:672002598 | https://github.com/weaviate/Verba | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:672002598 | https://github.com/weaviate/Verba | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 来源证据：v0.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.3.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_29616574b8474fb7a44c6d3350b062fd | https://github.com/weaviate/Verba/releases/tag/0.3.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 安全/权限坑 · 来源证据：v0.3.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.3.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8c5e79dc1cf3480b9792cbd54643bb14 | https://github.com/weaviate/Verba/releases/tag/0.3.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 安全/权限坑 · 来源证据：v2.1.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.2\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9dc754c525ec48808ee74f66f9694312 | https://github.com/weaviate/Verba/releases/tag/v2.1.2 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 13. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | issue_or_pr_quality=unknown\n\n## 14. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | release_recency=unknown\n\n<!-- canonical_name: weaviate/Verba; human_manual_source: deepwiki_human_wiki -->\n",
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "Human Manual / 人类版说明书"
    },
    "pitfall_log": {
      "asset_id": "pitfall_log",
      "filename": "PITFALL_LOG.md",
      "markdown": "# Pitfall Log / 踩坑日志\n\n项目：weaviate/Verba\n\n摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：1.0.1 Beautiful Verba。\n\n## 1. 安装坑 · 来源证据：1.0.1 Beautiful Verba\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：1.0.1 Beautiful Verba\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b08b22b1d7404da6ae9d8153c53602cd | https://github.com/weaviate/Verba/releases/tag/1.0.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 2. 安装坑 · 来源证据：v0.4.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.4.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_199393ab54bc4fd79d576c42dc3198f2 | https://github.com/weaviate/Verba/releases/tag/0.4.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：v1.0.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.0.3\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_90c577983a844f3ba246a181a8e03997 | https://github.com/weaviate/Verba/releases/tag/v1.0.3 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：v2.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.1.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0ec01ecbe8494b08a039e08f6bf68f01 | https://github.com/weaviate/Verba/releases/tag/v2.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:672002598 | https://github.com/weaviate/Verba | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | last_activity_observed missing\n\n## 7. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:672002598 | https://github.com/weaviate/Verba | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:672002598 | https://github.com/weaviate/Verba | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:672002598 | https://github.com/weaviate/Verba | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 来源证据：v0.3.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.3.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_29616574b8474fb7a44c6d3350b062fd | https://github.com/weaviate/Verba/releases/tag/0.3.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 安全/权限坑 · 来源证据：v0.3.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.3.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8c5e79dc1cf3480b9792cbd54643bb14 | https://github.com/weaviate/Verba/releases/tag/0.3.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 安全/权限坑 · 来源证据：v2.1.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.2\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9dc754c525ec48808ee74f66f9694312 | https://github.com/weaviate/Verba/releases/tag/v2.1.2 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。\n\n## 13. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | issue_or_pr_quality=unknown\n\n## 14. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:672002598 | https://github.com/weaviate/Verba | release_recency=unknown\n",
      "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
      "title": "Pitfall Log / 踩坑日志"
    },
    "prompt_preview": {
      "asset_id": "prompt_preview",
      "filename": "PROMPT_PREVIEW.md",
      "markdown": "# Verba - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for weaviate/Verba.\n\nProject:\n- Name: Verba\n- Repository: https://github.com/weaviate/Verba\n- Summary: Retrieval Augmented Generation (RAG) chatbot powered by Weaviate\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Retrieval Augmented Generation (RAG) chatbot powered by Weaviate\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Retrieval Augmented Generation (RAG) chatbot powered by Weaviate\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-introduction: Introduction to Verba. Produce one small intermediate artifact and wait for confirmation.\n2. page-rag-concepts: RAG Concepts in Verba. Produce one small intermediate artifact and wait for confirmation.\n3. page-component-architecture: Component Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. page-data-ingestion: Data Ingestion System. Produce one small intermediate artifact and wait for confirmation.\n5. page-chunking-strategies: Chunking Strategies. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/weaviate/Verba\n- https://github.com/weaviate/Verba#readme\n- README.md\n- CHANGELOG.md\n- goldenverba/verba_manager.py\n- goldenverba/components/interfaces.py\n- goldenverba/components/types.py\n- goldenverba/components/__init__.py\n- goldenverba/components/managers.py\n- goldenverba/components/reader/BasicReader.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
      "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
      "title": "Prompt Preview / 安装前试用 Prompt"
    },
    "quick_start": {
      "asset_id": "quick_start",
      "filename": "QUICK_START.md",
      "markdown": "# Quick Start / 官方入口\n\n项目：weaviate/Verba\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install goldenverba\n```\n\n来源：https://github.com/weaviate/Verba#readme\n\n## 来源\n\n- repo: https://github.com/weaviate/Verba\n- docs: https://github.com/weaviate/Verba#readme\n",
      "summary": "从项目官方 README 或安装文档提取的开工入口。",
      "title": "Quick Start / 官方入口"
    }
  },
  "validation_id": "dval_5a4f2866bee9484d877f3814456e0372"
}