{
  "canonical_name": "weaviate/Verba",
  "compilation_id": "pack_3863a80beba14dcfa8cfa9ec7880af95",
  "created_at": "2026-05-11T17:38:13.480664+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": 849,
    "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": "Retrieval Augmentation",
        "label_zh": "检索增强",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "core_capability-retrieval-augmentation",
        "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": 849,
        "license": "unknown",
        "note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
        "stars": 7694,
        "open_issues": 76,
        "pushed_at": null
      },
      "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> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 Verba 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Retrieval Augmented Generation (RAG) chatbot powered by Weaviate 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：Verba 简介。围绕“Verba 简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-features：核心功能特性。围绕“核心功能特性”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统整体架构。围绕“系统整体架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-frontend-structure：前端架构与组件。围绕“前端架构与组件”模拟一次用户任务，不展示安装或运行结果。\n5. page-backend-components：后端组件系统。围绕“后端组件系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Verba 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-features\n输入：用户提供的“核心功能特性”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统整体架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-frontend-structure\n输入：用户提供的“前端架构与组件”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-backend-components\n输入：用户提供的“后端组件系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Verba 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-features：Step 2 必须围绕“核心功能特性”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统整体架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-frontend-structure：Step 4 必须围绕“前端架构与组件”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-backend-components：Step 5 必须围绕“后端组件系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/weaviate/Verba\n- https://github.com/weaviate/Verba#readme\n- README.md\n- CHANGELOG.md\n- TECHNICAL.md\n- goldenverba/components/embedding/__init__.py\n- goldenverba/components/generation/__init__.py\n- goldenverba/components/chunking/__init__.py\n- goldenverba/server/api.py\n- goldenverba/verba_manager.py\n- goldenverba/components/interfaces.py\n- frontend/app/page.tsx\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 Verba 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n  2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\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-11 17:36:08 UTC\n\n## 目录\n\n- [Verba 简介](#page-introduction)\n- [核心功能特性](#page-features)\n- [系统整体架构](#page-architecture)\n- [前端架构与组件](#page-frontend-structure)\n- [后端组件系统](#page-backend-components)\n- [数据导入与处理](#page-data-ingestion)\n- [RAG 检索与生成流程](#page-rag-pipeline)\n- [模型集成](#page-model-integration)\n- [部署方式](#page-deployment)\n- [环境变量与配置](#page-configuration)\n\n<a id='page-introduction'></a>\n\n## Verba 简介\n\n### 相关页面\n\n相关主题：[核心功能特性](#page-features), [系统整体架构](#page-architecture)\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- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n- [frontend/app/page.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/page.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/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n- [frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n</details>\n\n# Verba 简介\n\nVerba（意为\"词语\"）是由 Weaviate 团队开发的开源 RAG（Retrieval-Augmented Generation，检索增强生成）应用框架，中文名称为\"Golden RAGtriever\"。该项目旨在为用户提供一个简洁友好的界面，快速构建和部署基于私有数据的问答系统。资料来源：[README.md:1]()\n\n## 项目概述\n\nVerba 是一个端到端的 RAG 解决方案，集成了文档导入、语义检索和大语言模型生成功能。用户可以在几步之内完成数据导入和问答配置，无需复杂的代码编写。资料来源：[setup.py:8]()\n\n### 核心特性\n\n| 特性 | 说明 |\n|------|------|\n| 多格式文档支持 | 支持 PDF、文本、CSV、Excel（xlsx/xls）、音频文件等 |\n| 多部署方式 | 支持 pip 安装、源码构建、Docker 部署 |\n| 多 AI 提供商 | OpenAI、Ollama、Novita、Upstage、Groq、Cohere 等 |\n| 可视化界面 | React 构建的现代化 Web 前端 |\n| 灵活配置 | 支持自定义 RAG 管道参数 |\n\n资料来源：[README.md:15-25]()\n\n## 技术架构\n\n### 技术栈\n\nVerba 采用前后端分离的架构设计：\n\n| 层级 | 技术选型 | 说明 |\n|------|----------|------|\n| 前端 | React / Next.js / TypeScript | 构建用户交互界面 |\n| 后端 | Python FastAPI | 提供 RESTful API 服务 |\n| 向量数据库 | Weaviate | 核心向量检索引擎 |\n| 部署环境 | Python 3.10-3.12 | 后端运行环境 |\n\n资料来源：[setup.py:5-6]()\n\n### 系统组件\n\n```mermaid\ngraph TD\n    A[用户界面层] --> B[前端 React 应用]\n    B --> C[FastAPI 后端服务]\n    C --> D[Weaviate 向量数据库]\n    C --> E[文档处理器]\n    C --> F[LLM 生成器]\n    E --> G[多格式 Reader]\n    F --> H[多模型 Generator]\n    G --> I[csv, xlsx, 音频, PDF...]\n    H --> J[OpenAI, Ollama, Novita...]\n```\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:1-50]()\n\n## 部署方式\n\nVerba 支持多种部署模式，满足不同用户的需求：\n\n### 部署模式对比\n\n| 部署方式 | 说明 | 适用场景 |\n|----------|------|----------|\n| Local | 使用本地 Weaviate 实例 | 开发测试 |\n| Docker | Docker Compose 编排部署 | 生产环境快速部署 |\n| Weaviate Cloud (WCS) | 云端托管服务 | 企业级应用 |\n| Custom | 自定义 Weaviate URL 和端口 | 已有 Weaviate 实例 |\n\n资料来源：[frontend/app/components/Login/LoginView.tsx:80-85]()\n\n### 安装方式\n\n```bash\n# 方式一：pip 安装\npip install goldenverba\n\n# 方式二：源码构建\ngit clone https://github.com/weaviate/Verba\npip install -e .\n\n# 方式三：Docker 部署\ngit clone https://github.com/weaviate/Verba\ndocker compose --env-file <your-env-file> up -d --build\n```\n\n资料来源：[README.md:15-35]()\n\n## 功能模块\n\n### 文档管理\n\nVerba 提供完整的文档导入和管理功能：\n\n- **导入方式**：支持单个文件、文件夹批量导入、URL 链接导入\n- **文件格式**：CSV、Excel（xlsx/xls）、PDF、音频文件、文本文件\n- **标签系统**：用户可为文档添加标签进行分类和过滤\n- **来源链接**：可添加原始文档的来源链接，方便溯源\n- **覆盖选项**：支持覆盖同名已存在的文档\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-80]()\n\n### 聊天问答\n\n用户可以通过聊天界面与数据交互：\n\n```mermaid\ngraph LR\n    A[用户提问] --> B[语义检索]\n    B --> C[相关文档块]\n    C --> D[LLM 生成]\n    D --> E[返回答案]\n    C --> F[展示引用来源]\n```\n\n- **语义检索**：基于向量相似度匹配相关文档块\n- **上下文展示**：显示检索到的文档片段及其来源\n- **配置选项**：可调整 RAG 管道的各项参数\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:80-120]()\n\n### 系统设置\n\nSettings 页面提供系统级配置功能：\n\n| 功能 | 说明 |\n|------|------|\n| 重置文档 | 清空所有已导入的文档和块 |\n| 重置配置 | 恢复默认配置参数 |\n| 重置建议 | 清空自动补全建议缓存 |\n| 完全重置 | 删除所有 Verba 相关集合 |\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:30-60]()\n\n## 导航结构\n\n前端应用包含以下主要页面：\n\n| 页面 | 路由标识 | 功能 |\n|------|----------|------|\n| Chat | `CHAT` | 聊天问答主界面 |\n| Documents | `DOCUMENTS` | 文档浏览与管理 |\n| Import Data | `ADD` | 数据导入功能 |\n| Settings | `SETTINGS` | 系统配置 |\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:30-60]()\n\n## 版本历史\n\nVerba 采用语义化版本号，当前版本为 2.1.3。主要版本更新如下：\n\n| 版本 | 特性 |\n|------|------|\n| 2.1.3 | 新增 OLLAMA 环境变量支持、CSV/Excel 文件支持 |\n| 2.1.2 | 新增 Novita 生成器、修复 spaCy 语言问题 |\n| 2.1.1 | 动态获取 OpenAI 模型名称 |\n| 2.1.0 | 新增 Upstage 支持、Groq 支持、AssemblyAI 音频读取 |\n\n资料来源：[CHANGELOG.md:1-30]()\n\n## 环境配置\n\nVerba 支持通过环境变量配置 API 密钥和部署选项：\n\n### 主要环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `DEFAULT_DEPLOYMENT` | 默认部署模式（Local/Docker/Weaviate/Custom） |\n| `OLLAMA_MODEL` | Ollama 使用的模型名称 |\n| `OLLAMA_EMBED_MODEL` | Ollama 嵌入模型名称 |\n| `OPENAI_API_KEY` | OpenAI API 密钥 |\n| `WEAVIATE_URL` | Weaviate 实例地址 |\n| `WEAVIATE_API_KEY` | Weaviate API 密钥 |\n\n资料来源：[README.md:40-60]()\n\n## 快速入门\n\n### 步骤一：选择部署方式\n\n首次启动时，用户需要选择连接方式：\n\n1. **Weaviate** - 连接 Weaviate Cloud Service\n2. **Docker** - 使用 Docker 部署的本地实例\n3. **Custom** - 自定义 Weaviate URL 和端口\n4. **Local** - 使用本地完整部署\n\n资料来源：[frontend/app/components/Login/LoginView.tsx:80-120]()\n\n### 步骤二：导入数据\n\n进入\"Import Data\"页面后，用户可以：\n\n- 选择\"Add Files\"添加单个或多个文件\n- 选择\"Add Directory\"批量导入文件夹\n- 选择\"Add URL\"通过链接导入\n\n导入后可在\"Overview\"或\"Configure\"标签页中单独配置每个文件。资料来源：[README.md:65-70]()\n\n### 步骤三：开始问答\n\n数据导入完成后，切换到\"Chat\"页面即可开始提问。系统会根据检索到的相关文档块生成回答，用户可以查看答案的引用来源。资料来源：[README.md:72-75]()\n\n## 项目结构\n\n```\nVerba/\n├── frontend/                    # React 前端应用\n│   └── app/\n│       ├── components/          # React 组件\n│       │   ├── Chat/            # 聊天相关组件\n│       │   ├── Ingestion/       # 数据导入组件\n│       │   ├── Login/           # 登录相关组件\n│       │   ├── Navigation/      # 导航组件\n│       │   └── Settings/        # 设置组件\n│       └── page.tsx             # 主页面\n├── goldenverba/                 # Python 后端包\n│   └── server/                  # 后端服务代码\n├── README.md                    # 项目说明\n├── CHANGELOG.md                 # 变更日志\n├── setup.py                     # 包配置\n└── docker-compose.yml           # Docker 编排文件\n```\n\n## 下一步\n\n- 阅读完整的 [技术文档](./TECHNICAL.md) 了解架构细节\n- 查看 [贡献指南](./CONTRIBUTING.md) 参与项目开发\n- 访问 [GitHub 仓库](https://github.com/weaviate/Verba) 获取最新更新\n\n---\n\n<a id='page-features'></a>\n\n## 核心功能特性\n\n### 相关页面\n\n相关主题：[Verba 简介](#page-introduction), [模型集成](#page-model-integration), [数据导入与处理](#page-data-ingestion)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/weaviate/Verba/blob/main/README.md)\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- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\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/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- [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- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n</details>\n\n# 核心功能特性\n\nVerba（Golden RAGtriever）是一款开源的检索增强生成（RAG）应用框架，旨在为用户提供简化的数据交互和问答体验。该项目基于 Python 3.10-3.12 构建，集成了 Weaviate 向量数据库，支持多种数据源导入、智能分块、语义检索和 LLM 生成功能。资料来源：[setup.py:5](https://github.com/weaviate/Verba/blob/main/setup.py)\n\n## 系统架构概述\n\nVerba 采用前后端分离的微服务架构，前端使用 React/Next.js 构建响应式界面，后端基于 FastAPI 提供 API 服务。系统支持多种部署模式，以适应不同的使用场景。\n\n```mermaid\ngraph TD\n    A[用户界面层] --> B[前端 React 应用]\n    B --> C[WebSocket / REST API]\n    C --> D[FastAPI 后端服务]\n    D --> E[Weaviate 向量数据库]\n    D --> F[LLM 生成器]\n    D --> G[嵌入模型]\n    E --> H[数据存储层]\n    F --> I[外部 LLM API]\n    G --> J[嵌入服务]\n```\n\n## 部署模式\n\nVerba 提供四种部署模式，满足从本地开发到云端生产环境的不同需求。\n\n| 部署模式 | 描述 | 适用场景 |\n|---------|------|---------|\n| Local | 使用 Weaviate Embedded 本地嵌入式实例 | 开发测试 |\n| Docker | 通过 Docker Compose 启动完整容器化环境 | 本地部署 |\n| Weaviate Cloud (WCS) | 连接 Weaviate 云服务 | 云端生产环境 |\n| Custom | 自定义 Weaviate 实例 URL、端口和 API 密钥 | 企业内部部署 |\n\n资料来源：[README.md:40-44](https://github.com/weaviate/Verba/blob/main/README.md)\n\n### 部署模式选择界面\n\n在 `LoginView.tsx` 组件中实现了部署模式选择逻辑，用户可以通过界面选择所需的部署方式。\n\n```typescript\n// frontend/app/components/Login/LoginView.tsx\n{production == \"Local\" && (\n  <VerbaButton\n    title=\"Weaviate\"\n    Icon={FaDatabase}\n    onClick={() => setSelectedDeployment(\"Weaviate\")}\n  />\n)}\n```\n\n## 文档导入与处理\n\nVerba 提供灵活的文档导入功能，支持多种数据格式和来源。\n\n### 支持的文件格式\n\n在 2.1.3 版本中，DefaultReader 扩展了以下文件格式支持：\n\n| 文件类型 | 扩展名 | 描述 |\n|---------|-------|------|\n| CSV 表格 | `.csv` | 逗号分隔值文件 |\n| Excel 工作簿 | `.xlsx`, `.xls` | Microsoft Excel 文件 |\n| 纯文本 | `.txt` | 纯文本文件 |\n| Markdown | `.md` | Markdown 格式文档 |\n| HTML | `.html`, `.htm` | 网页内容 |\n\n资料来源：[CHANGELOG.md:8-10](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n### 文档导入流程\n\n```mermaid\ngraph LR\n    A[选择数据源] --> B[添加文件/目录/URL]\n    B --> C{数据源类型}\n    C -->|文件| D[文件读取器]\n    C -->|目录| E[批量文件处理]\n    C -->|URL| F[网页抓取器]\n    D --> G[文档解析]\n    E --> G\n    F --> G\n    G --> H[文档对象创建]\n    H --> I[配置处理管道]\n    I --> J[存储至 Weaviate]\n```\n\n### 导入配置功能\n\n`BasicSettingView.tsx` 组件提供了文档导入时的基本配置选项：\n\n- **来源链接（Source Link）**：添加文档原始来源的引用链接，用户可通过文档浏览器中的\"查看来源\"按钮访问\n- **标签（Labels）**：为文档添加自定义标签，便于分类和检索\n\n```typescript\n// frontend/app/components/Ingestion/BasicSettingView.tsx\n<div className=\"flex gap-2 justify-between items-center text-text-verba\">\n  <p className=\"flex min-w-[8vw]\">Source Link</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={source}\n      onChange={handleSourceChange}\n      disabled={blocked}\n    />\n  </label>\n</div>\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n\n## 文档对象模型\n\nVerba 使用统一的 `Document` 类表示所有文档内容，该类封装了文档的元数据和内容信息。\n\n### Document 类结构\n\n```python\n# goldenverba/components/document.py\n@dataclass\nclass Document:\n    title: str              # 文档标题\n    content: str            # 文档正文内容\n    extension: str          # 文件扩展名\n    doc_id: str = \"\"        # 文档唯一标识\n    content_id: str = \"\"   # 内容块唯一标识\n    labels: List[str] = field(default_factory=list)  # 标签列表\n    source: str = \"\"        # 来源链接\n    fileSize: int = 0      # 文件大小\n    metadata: str = \"\"     # 元数据字符串\n    meta: dict = field(default_factory=dict)  # 元数据字典\n```\n\n资料来源：[goldenverba/components/document.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/document.py)\n\n### 创建文档工厂函数\n\n```python\ndef create_document(content: str, fileConfig: FileConfig) -> Document:\n    \"\"\"从文件内容创建 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## RAG 处理管道\n\nVerba 实现了完整的 RAG（检索增强生成）处理管道，包括读取器、分块器、嵌入器和生成器四个核心组件。\n\n### 组件架构\n\n```mermaid\ngraph TD\n    subgraph RAG管道\n        A[Reader 读取器] --> B[Chunking 分块器]\n        B --> C[Embedding 嵌入器]\n        C --> D[Vector Store 向量存储]\n        D --> E[Retrieval 检索]\n        E --> F[Generator 生成器]\n        F --> G[Response 响应]\n    end\n```\n\n### HTML 读取器实现\n\n`HTMLReader.py` 提供了网页内容抓取和转换功能，支持以下配置选项：\n\n| 配置项 | 类型 | 默认值 | 描述 |\n|-------|------|-------|------|\n| URLs | string[] | [] | 要抓取的 URL 列表 |\n| Convert To Markdown | bool | false | 是否转换为 Markdown 格式 |\n| Recursive | bool | false | 是否递归抓取链接页面 |\n| Max Depth | number | 3 | 递归抓取的最大深度 |\n\n```python\n# goldenverba/components/reader/HTMLReader.py\nasync def load(self, config: dict, fileConfig: FileConfig) -> list[Document]:\n    reader = BasicReader()\n    urls = config[\"URLs\"].values\n    to_markdown = config[\"Convert To Markdown\"].value\n    recursive = config[\"Recursive\"].value\n    max_depth = int(config[\"Max Depth\"].value)\n    \n    documents = []\n    processed_urls = set()\n    \n    async with aiohttp.ClientSession() as session:\n        for url in urls:\n            await self.process_url(...)\n```\n\n资料来源：[goldenverba/components/reader/HTMLReader.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/reader/HTMLReader.py)\n\n## 聊天问答界面\n\nVerba 的聊天界面允许用户使用自然语言查询已导入的文档，系统会返回语义相关的文档片段并生成答案。\n\n### 聊天流程\n\n```mermaid\nsequenceDiagram\n    participant U as 用户\n    participant C as 前端界面\n    participant S as 后端服务\n    participant W as Weaviate\n    participant L as LLM\n    \n    U->>C: 输入问题\n    C->>S: 发送查询请求\n    S->>W: 语义检索相关片段\n    W-->>S: 返回 Top-K 相关片段\n    S->>L: 发送上下文+问题\n    L-->>S: 生成回答\n    S-->>C: 返回答案+引用片段\n    C->>U: 显示结果\n```\n\n### 界面组件结构\n\n`ChatInterface.tsx` 实现了完整的聊天交互界面，包含以下功能区域：\n\n- **消息显示区**：展示用户问题和系统回答\n- **配置面板**：调整 RAG 管道参数\n- **输入区域**：文本输入框用于提交问题\n- **状态指示器**：显示检索（Retrieving）和生成（Generating）状态\n\n```typescript\n// frontend/app/components/Chat/ChatInterface.tsx\n<span className=\"text-text-alt-verba loading loading-dots loading-md\"></span>\n<p className=\"text-text-alt-verba\">\n  {fetchingStatus === \"CHUNKS\" && \"Retrieving...\"}\n  {fetchingStatus === \"RESPONSE\" && \"Generating...\"}\n</p>\n```\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n\n### 取消操作\n\n用户可以随时取消正在进行的检索或生成操作：\n\n```typescript\n<button\n  onClick={() => {\n    setFetchingStatus(\"DONE\");\n    isFetching.current = false;\n  }}\n  className=\"btn btn-circle btn-sm bg-bg-alt-verba hover:bg-warning-verba\"\n>\n  <MdCancel size={15} />\n</button>\n```\n\n## 生成器与嵌入器\n\nVerba 支持多种 LLM 提供商和嵌入模型，用户可根据需求灵活配置。\n\n### 支持的 LLM 提供商\n\n| 提供商 | 类型 | 配置方式 |\n|-------|------|---------|\n| OpenAI | 云端 API | API Key + URL |\n| Anthropic | 云端 API | API Key |\n| Cohere | 云端 API | API Key |\n| Ollama | 本地/自托管 | 本地服务 URL + 模型名称 |\n| Upstage | 云端 API | API Key |\n| Novita | 云端 API | API Key |\n| Groq | 云端 API | API Key |\n\n资料来源：[CHANGELOG.md:4-24](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n### 环境变量配置\n\nVerba 支持通过环境变量配置模型：\n\n| 环境变量 | 描述 |\n|---------|------|\n| `OLLAMA_MODEL` | Ollama 默认模型 |\n| `OLLAMA_EMBED_MODEL` | Ollama 嵌入模型 |\n| `DEFAULT_DEPLOYMENT` | 默认部署模式 |\n\n## 系统设置与管理\n\n### InfoView 设置面板\n\n`InfoView.tsx` 组件提供了全面的系统管理功能：\n\n```mermaid\ngraph TD\n    A[设置面板] --> B[集群信息]\n    A --> C[集合管理]\n    A --> D[重置操作]\n    \n    B --> B1[节点状态]\n    B --> B2[分片信息]\n    \n    C --> C1[集合列表]\n    C --> C2[对象计数]\n    \n    D --> D1[重置文档]\n    D --> D2[重置配置]\n    D --> D3[重置建议]\n    D --> D4[重置全部]\n```\n\n### 重置操作\n\n| 操作 | 描述 | 影响范围 |\n|-----|------|---------|\n| Reset Documents | 清除所有文档和分块 | 集合中的文档数据 |\n| Reset Config | 重置配置参数 | RAG 管道配置 |\n| Reset Suggestions | 重置自动完成建议 | 搜索建议缓存 |\n| Reset Verba | 完整重置 | 删除所有 Verba 相关集合 |\n\n```typescript\n// frontend/app/components/Settings/InfoView.tsx\n<UserModalComponent\n  modal_id=\"reset-documents\"\n  title=\"Reset Documents\"\n  text=\"Are you sure you want to reset all documents? This will clear all documents and chunks from Verba.\"\n  triggerAccept={resetDocuments}\n  triggerString=\"Reset\"\n/>\n```\n\n## 导航与界面布局\n\n### 顶部导航栏\n\n`NavbarComponent.tsx` 实现了应用的主要导航结构：\n\n```mermaid\ngraph LR\n    A[导航栏] --> B[Chat 聊天]\n    A --> C[Documents 文档]\n    A --> D[Import Data 导入数据]\n    A --> E[Settings 设置]\n    \n    style A fill:#e1f5fe\n    style B fill:#b3e5fc\n    style C fill:#b3e5fc\n    style D fill:#b3e5fc\n    style E fill:#b3e5fc\n```\n\n### 导航按钮组件\n\n```typescript\n// frontend/app/components/Navigation/NavbarComponent.tsx\n<NavbarButton\n  hide={false}\n  Icon={IoChatbubbleSharp}\n  title=\"Chat\"\n  currentPage={currentPage}\n  setCurrentPage={setCurrentPage}\n  setPage=\"CHAT\"\n/>\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\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n\n## 文档浏览器\n\n### ContentView 文档内容展示\n\n`ContentView.tsx` 组件提供了文档内容的分页浏览功能：\n\n- **分块导航**：支持按块（Chunk）或按页（Page）浏览\n- **内容渲染**：将文档内容片段渲染为可读文本\n- **标签显示**：展示文档关联的标签\n\n```typescript\n// frontend/app/components/Document/ContentView.tsx\n<div className=\"flex justify-center items-center gap-2 p-3 bg-bg-alt-verba\">\n  <VerbaButton\n    title={\"Previous \" + (chunkScores ? \"Chunk\" : \"Page\")}\n    onClick={previousPage}\n    className=\"btn-sm min-w-min max-w-[200px]\"\n  />\n  <div className=\"flex items-center\">\n    <p className=\"text-xs text-text-verba\">\n      {chunkScores ? \"Chunk \" : \"Page \"} {page}\n    </p>\n  </div>\n  <VerbaButton\n    title={\"Next \" + (chunkScores ? \"Chunk\" : \"Page\")}\n    onClick={nextPage}\n  />\n</div>\n```\n\n## 快速入门\n\n### 安装方式\n\nVerba 提供三种安装方式：\n\n| 安装方式 | 命令 | 适用场景 |\n|---------|------|---------|\n| pip 安装 | `pip install goldenverba` | 快速体验 |\n| 源码构建 | `git clone && pip install -e .` | 开发调试 |\n| Docker 部署 | `docker compose --env-file <env-file> up -d --build` | 生产环境 |\n\n```bash\n# pip 安装\npip install goldenverba\n\n# 源码构建\ngit clone https://github.com/weaviate/Verba\npip install -e .\n\n# Docker 部署\ngit clone https://github.com/weaviate/Verba\ndocker compose --env-file <your-env-file> up -d --build\n```\n\n### 环境变量配置\n\n在项目根目录创建 `.env` 文件配置 API 密钥和环境变量。Verba 会自动读取该文件中的配置。\n\n> 注意：仅设置需要使用的环境变量，缺失或错误的值可能导致运行错误。\n\n资料来源：[README.md:58-75](https://github.com/weaviate/Verba/blob/main/README.md)\n\n## 版本历史\n\n| 版本 | 发布内容 |\n|-----|---------|\n| 2.1.3 | 新增 CSV/Excel 支持，添加 Ollama 环境变量 |\n| 2.1.2 | 添加 Novita 生成器，修复 spaCy 语言问题 |\n| 2.1.1 | OpenAI 模型名称动态获取 |\n| 2.1.0 | 添加 Upstage 组件，新增 Custom 部署模式 |\n\n资料来源：[CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n---\n\n<a id='page-architecture'></a>\n\n## 系统整体架构\n\n### 相关页面\n\n相关主题：[Verba 简介](#page-introduction), [前端架构与组件](#page-frontend-structure), [后端组件系统](#page-backend-components)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [TECHNICAL.md](https://github.com/weaviate/Verba/blob/main/TECHNICAL.md)\n- [goldenverba/server/api.py](https://github.com/weaviate/Verba/blob/main/goldenverba/server/api.py)\n- [goldenverba/verba_manager.py](https://github.com/weaviate/Verba/blob/main/goldenverba/verba_manager.py)\n- [goldenverba/components/interfaces.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/interfaces.py)\n- [frontend/app/page.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/page.tsx)\n</details>\n\n# 系统整体架构\n\n## 概述\n\nVerba（Golden RAGtriever）是一个开源的检索增强生成（RAG）应用程序，旨在为用户提供一个简化、易用的 RAG 解决方案。该项目由 Weaviate 团队开发维护，支持多种部署方式和 LLM 提供商集成。资料来源：[README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n\n## 技术栈概览\n\nVerba 采用前后端分离的架构设计，主要由以下技术组件构成：\n\n| 层次 | 技术选型 | 说明 |\n|------|----------|------|\n| 前端框架 | Next.js (React) | 用户界面与交互逻辑 |\n| 后端框架 | FastAPI + Uvicorn | RESTful API 服务 |\n| 数据存储 | Weaviate | 向量数据库与全文检索 |\n| 包管理 | setuptools | Python 包发布配置 |\n| 运行时 | Python 3.10-3.12 | 后端运行环境 |\n\n资料来源：[setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n\n## 系统架构图\n\n```mermaid\ngraph TD\n    subgraph 前端层[\"前端层 (Next.js)\"]\n        A[用户界面] --> B[页面路由]\n        B --> C[组件库]\n        C --> D[状态管理]\n    end\n    \n    subgraph 后端层[\"后端层 (FastAPI)\"]\n        E[API 路由] --> F[Verba Manager]\n        F --> G[组件系统]\n        G --> H[Weaviate 客户端]\n    end\n    \n    subgraph 数据层[\"数据层 (Weaviate)\"]\n        I[向量存储] --> J[集合与对象]\n    end\n    \n    K[文档导入] --> E\n    L[聊天查询] --> E\n    E --> H\n    H --> I\n    \n    M[LLM 提供商] --> G\n    N[嵌入模型] --> G\n```\n\n## 核心组件架构\n\n### 前端组件结构\n\n前端采用 Next.js 框架构建，主要包含以下核心组件模块：\n\n| 组件模块 | 文件路径 | 功能描述 |\n|----------|----------|----------|\n| 导航组件 | `frontend/app/components/Navigation/` | 页面导航与菜单 |\n| 聊天组件 | `frontend/app/components/Chat/` | 对话界面与消息展示 |\n| 设置组件 | `frontend/app/components/Settings/` | 配置管理界面 |\n| 登录组件 | `frontend/app/components/Login/` | 部署选择与初始配置 |\n| 导入组件 | `frontend/app/components/Ingestion/` | 数据导入功能 |\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n\n### 后端核心模块\n\n#### Verba Manager\n\nVerba Manager 是系统的核心管理单元，负责协调各个组件之间的交互。该模块处理文档管理、RAG 配置、用户凭证等核心业务逻辑。\n\n```python\n# 核心管理功能\n- 文档生命周期管理\n- RAG 管道配置\n- 凭证验证与存储\n- 部署环境适配\n```\n\n资料来源：[goldenverba/verba_manager.py](https://github.com/weaviate/Verba/blob/main/goldenverba/verba_manager.py)\n\n#### 组件接口系统\n\nVerba 采用基于接口的组件化设计，所有核心功能都通过标准化接口实现：\n\n```mermaid\ngraph LR\n    A[Reader 接口] --> B[文档读取]\n    C[Embedder 接口] --> D[向量嵌入]\n    E[Generator 接口] --> F[文本生成]\n    G[Chunker 接口] --> H[文档分块]\n```\n\n资料来源：[goldenverba/components/interfaces.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/interfaces.py)\n\n### 文档对象模型\n\n```mermaid\nclassDiagram\n    class Document {\n        +str title\n        +str content\n        +str extension\n        +str fileSize\n        +list labels\n        +str source\n        +dict meta\n        +str metadata\n    }\n    \n    class FileConfig {\n        +str filename\n        +str extension\n        +str content\n        +str source\n        +list labels\n        +str file_size\n        +dict metadata\n    }\n    \n    Document --> FileConfig : create from\n```\n\n资料来源：[goldenverba/components/document.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/document.py)\n\n## 部署架构\n\nVerba 支持多种部署模式，以适应不同的使用场景：\n\n```mermaid\ngraph TD\n    A[启动 Verba] --> B{部署模式选择}\n    \n    B --> C[Local 模式]\n    B --> D[Docker 模式]\n    B --> E[Weaviate 云服务]\n    B --> F[Custom 自定义]\n    \n    C --> G[本地 Ollama]\n    C --> H[本地 HuggingFace]\n    \n    D --> I[Docker Compose]\n    \n    E --> J[WCS 云端]\n    \n    F --> K[自定义 Weaviate 实例]\n    K --> L[自定义 API 端点]\n```\n\n资料来源：[frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n\n### 部署模式对比\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| Local | 本地 Ollama/HuggingFace | 开发测试 |\n| Docker | Docker Compose 部署 | 快速体验 |\n| Weaviate | Weaviate Cloud Services | 生产环境 |\n| Custom | 自定义 Weaviate 实例 | 已有基础设施 |\n\n## RAG 处理流程\n\n```mermaid\ngraph LR\n    A[数据导入] --> B[文档读取 Reader]\n    B --> C[分块处理 Chunker]\n    C --> D[向量化 Embedder]\n    D --> E[Weaviate 存储]\n    \n    F[用户查询] --> G[向量化查询]\n    G --> H[向量检索]\n    H --> I[上下文组装]\n    I --> J[LLM 生成]\n    J --> K[返回结果]\n```\n\n### 聊天界面交互\n\n聊天模块负责用户与 RAG 系统之间的交互：\n\n```mermaid\nstateDiagram-v2\n    [*] --> 空闲状态: 页面加载\n    空闲状态 --> 检索中: 用户发送消息\n    检索中 --> 生成中: 获取到上下文\n    生成中 --> 空闲状态: 生成完成\n    检索中 --> 空闲状态: 取消操作\n    生成中 --> 空闲状态: 取消操作\n```\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n\n## 前端页面结构\n\n```mermaid\ngraph TD\n    A[主页面] --> B[导航栏]\n    A --> C[内容区域]\n    A --> D[页脚]\n    \n    B --> B1[Chat 聊天]\n    B --> B2[Documents 文档]\n    B --> B3[Import Data 导入]\n    B --> B4[Settings 设置]\n    \n    C --> C1{生产模式判断}\n    C1 -->|非 Demo| B3\n    C1 -->|Demo| 隐藏导入\n```\n\n资料来源：[frontend/app/page.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/page.tsx)\n\n## API 服务架构\n\nFastAPI 后端提供以下核心服务接口：\n\n| 接口类别 | 功能 | 通信方式 |\n|----------|------|----------|\n| 文档管理 | 上传、查询、删除文档 | REST API |\n| RAG 配置 | 模型选择、参数调整 | REST API |\n| 聊天接口 | 查询处理与响应生成 | WebSocket + REST |\n| 系统状态 | 健康检查、配置获取 | REST API |\n\n资料来源：[goldenverba/server/api.py](https://github.com/weaviate/Verba/blob/main/goldenverba/server/api.py)\n\n## 初始化流程\n\n```mermaid\nsequenceDiagram\n    participant U as 用户\n    participant F as 前端\n    participant B as 后端 API\n    participant W as Weaviate\n    \n    U->>F: 访问应用\n    F->>B: 健康检查\n    B->>W: 连接验证\n    W-->>B: 连接状态\n    B-->>F: 部署配置\n    F->>U: 显示登录界面\n    \n    U->>F: 选择部署模式\n    F->>B: 验证凭证\n    B->>W: 初始化集合\n    W-->>B: 初始化完成\n    B-->>F: 登录成功\n    F->>U: 进入主界面\n```\n\n## 环境配置\n\n系统通过环境变量进行配置管理：\n\n| 变量名 | 说明 | 示例值 |\n|--------|------|--------|\n| `DEFAULT_DEPLOYMENT` | 默认部署模式 | Local/Docker/Weaviate/Custom |\n| `OLLAMA_MODEL` | Ollama 模型名称 | llama2 |\n| `OLLAMA_EMBED_MODEL` | Ollama 嵌入模型 | nomic-embed-text |\n| `WEAVIATE_URL` | Weaviate 连接地址 | https://xxx.weaviate.cloud |\n| `WEAVIATE_API_KEY` | Weaviate API 密钥 | 保密 |\n\n资料来源：[CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n## 依赖关系\n\n```mermaid\ngraph TD\n    A[goldenverba] --> B[weaviate-client]\n    A --> C[fastapi]\n    A --> D[uvicorn]\n    A --> E[click]\n    \n    F[前端] --> G[Next.js]\n    F --> H[React]\n    F --> I[daisyUI]\n```\n\n核心依赖版本：\n\n- Python: 3.10.0 - 3.12.0\n- weaviate-client: 4.9.6\n- fastapi: 0.111.1\n- uvicorn: 0.29.0\n\n资料来源：[setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n\n## 总结\n\nVerba 采用现代化的前后端分离架构，通过组件化设计实现了高度的灵活性和可扩展性。系统支持多种部署模式，能够适应从本地开发到云端生产的各种使用场景。RAG 管道的模块化设计使得用户可以方便地切换不同的 LLM 提供商和嵌入模型，同时保持核心功能的稳定性和一致性。\n\n---\n\n<a id='page-frontend-structure'></a>\n\n## 前端架构与组件\n\n### 相关页面\n\n相关主题：[系统整体架构](#page-architecture), [后端组件系统](#page-backend-components), [RAG 检索与生成流程](#page-rag-pipeline)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\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/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/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.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/Document/ContentView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Document/ContentView.tsx)\n- [frontend/app/components/Ingestion/FileSelectionView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/FileSelectionView.tsx)\n- [frontend/app/page.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/page.tsx)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n</details>\n\n# 前端架构与组件\n\n## 概述\n\nVerba 前端是基于 Next.js 构建的 React 应用，采用组件化架构设计。该应用作为 RAG（检索增强生成）系统的用户界面，提供聊天交互、文档管理、数据导入和系统设置等功能。前端使用 TypeScript 开发，通过 WebSocket 与后端服务通信，并使用 Tailwind CSS 和 daisyUI 进行样式管理。资料来源：[setup.py:1-12]()\n\n## 技术栈\n\n| 技术类别 | 技术选型 | 用途 |\n|---------|---------|------|\n| 框架 | Next.js | 应用框架与路由管理 |\n| 语言 | TypeScript | 类型安全的开发 |\n| UI 库 | React + daisyUI | 组件与样式系统 |\n| 样式 | Tailwind CSS | 原子化 CSS 样式 |\n| 状态管理 | React Context + useRef | 组件状态与全局状态 |\n| 实时通信 | Socket.IO | WebSocket 双向通信 |\n| 渲染 | ReactMarkdown + SyntaxHighlighter | Markdown 与代码高亮 |\n\n## 组件架构\n\n### 组件目录结构\n\nVerba 前端组件采用功能模块化组织，所有组件位于 `frontend/app/components/` 目录下，按功能分为以下子目录：\n\n```\nfrontend/app/components/\n├── Chat/           # 聊天相关组件\n├── Document/       # 文档浏览组件\n├── Ingestion/      # 数据导入组件\n├── Login/          # 登录与初始化组件\n├── Navigation/     # 导航组件\n└── Settings/       # 设置组件\n```\n\n资料来源：[frontend/app/components/Chat/ChatMessage.tsx](), [frontend/app/components/Navigation/NavbarComponent.tsx]()\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n    A[主页面 page.tsx] --> B[NavbarComponent 导航栏]\n    A --> C[主内容区域]\n    \n    C --> D{currentPage 状态}\n    D -->|CHAT| E[ChatInterface 聊天界面]\n    D -->|DOCUMENTS| F[DocumentView 文档视图]\n    D -->|ADD| G[IngestionView 导入视图]\n    D -->|SETTINGS| H[InfoView 设置视图]\n    D -->|LOGIN| I[LoginView 登录视图]\n    \n    E --> J[ChatMessage 消息组件]\n    E --> K[ChatConfig 聊天配置]\n    \n    G --> L[FileSelectionView 文件选择]\n    G --> M[BasicSettingView 基础设置]\n    \n    B --> N[StatusMessenger 状态消息]\n```\n\n## 导航系统\n\n### 导航栏组件\n\nNavbarComponent 是应用的主导航组件，负责页面路由切换和状态显示。该组件根据 `production` 环境变量决定是否显示特定功能按钮。\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:1-150]()\n\n**导航按钮配置表：**\n\n| 按钮标题 | 图标 | 页面路由 | 显示条件 |\n|---------|------|---------|---------|\n| Chat | IoChatbubbleSharp | CHAT | 始终显示 |\n| Import Data | IoMdAddCircle | ADD | production !== \"Demo\" |\n| Documents | IoDocumentSharp | DOCUMENTS | 始终显示 |\n| Settings | IoSettingsSharp | SETTINGS | production !== \"Demo\" |\n\n导航栏支持响应式设计，在移动端（md 断点以下）以汉堡菜单形式展示，在桌面端以横向按钮组形式展示。组件使用 `useState` 管理当前页面状态，通过 `setCurrentPage` 回调向上层组件传递页面变更。资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:50-100]()\n\n### 状态消息组件\n\nStatusMessengerComponent 提供全局状态通知功能，通过 `AnimatePresence` 实现动画效果。消息根据类型（info、success、error）显示不同颜色，消息有效期为 5 秒。资料来源：[frontend/app/components/Navigation/StatusMessenger.tsx:1-40]()\n\n```mermaid\nsequenceDiagram\n    participant Parent as 父组件\n    participant StatusMessenger\n    participant Message as 消息队列\n    \n    Parent->>StatusMessenger: addStatusMessage(type, message)\n    StatusMessenger->>Message: 添加消息到队列\n    Note over Message: 设置 timestamp\n    StatusMessenger->>StatusMessenger: 过滤 5 秒内的消息\n    StatusMessenger->>StatusMessenger: 动画显示消息\n    Note over StatusMessenger: 5 秒后自动移除\n```\n\n## 聊天模块\n\n### 聊天界面组件\n\nChatInterface 是聊天功能的核心组件，管理消息列表、输入框和状态显示。组件支持以下消息类型：\n\n- `user`：用户发送的消息，右对齐显示\n- `system`：系统响应，左对齐显示，支持 Markdown 渲染\n- `error`：错误提示，使用警告色背景\n- `retrieval`：检索状态信息\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:1-200]()\n\n**消息状态与样式映射表：**\n\n| 消息类型 | 背景色类名 | 排列方式 | 特殊处理 |\n|---------|-----------|---------|---------|\n| user | bg-primary-verba | 右对齐 | 无 |\n| system | bg-bg-alt-verba | 左对齐 | Markdown 渲染 |\n| error | bg-warning-verba | 左对齐 | 无 |\n| retrieval | bg-bg-verba | 左对齐 | 无 |\n\n聊天界面包含实时检索状态指示器，显示 \"Retrieving...\" 或 \"Generating...\" 状态，用户可通过取消按钮终止请求。组件使用 `useRef` 管理 `isFetching` 状态以避免闭包问题。资料来源：[frontend/app/components/Chat/ChatInterface.tsx:80-120]()\n\n### 聊天消息组件\n\nChatMessage 负责渲染单条聊天消息，支持富文本内容展示。对于 system 类型消息，组件使用 ReactMarkdown 和 SyntaxHighlighter 进行 Markdown 解析和代码语法高亮。资料来源：[frontend/app/components/Chat/ChatMessage.tsx:1-100]()\n\n代码高亮支持根据主题（dark/light）切换样式：\n- **暗色主题**：使用 oneDark 配色\n- **亮色主题**：使用 oneLight 配色\n\n组件还支持 `cached` 属性，当消息为缓存内容时显示数据库图标。资料来源：[frontend/app/components/Chat/ChatMessage.tsx:30-60]()\n\n## 文档管理模块\n\n### 文档内容视图\n\nContentView 组件提供文档和 Chunk 的分页浏览功能。组件支持两种内容模式：\n\n1. **Chunk 模式**：显示检索到的文档片段，配合相关性分数\n2. **Page 模式**：显示原始文档分页\n\n资料来源：[frontend/app/components/Document/ContentView.tsx:1-150]()\n\n**内容显示特征表：**\n\n| 特征 | 显示条件 | 样式 |\n|-----|---------|------|\n| Chunk ID | chunkScores 存在 | 圆角标签 bg-bg-alt-verba |\n| 相关性标识 | score > 0 | 圆角标签 bg-primary-verba + 星星图标 |\n| 代码块 | 内容包含代码 | SyntaxHighlighter 高亮 |\n\n组件使用 Previous/Next 按钮进行分页导航，分页逻辑根据当前模式（Chunk 或 Page）显示不同的按钮文本。资料来源：[frontend/app/components/Document/ContentView.tsx:100-130]()\n\n## 数据导入模块\n\n### 文件选择视图\n\nFileSelectionView 组件管理导入文件的列表展示和选择状态。组件支持多种 Reader 类型筛选，包括 URL 类型 Reader 的下拉菜单选择。资料来源：[frontend/app/components/Ingestion/FileSelectionView.tsx:1-100]()\n\n**文件组件交互流程：**\n\n```mermaid\ngraph LR\n    A[FileSelectionView] --> B[FileComponent 列表]\n    B --> C{用户操作}\n    C -->|选择| D[setSelectedFileData]\n    C -->|删除| E[handleDeleteFile]\n    C -->|添加URL| F[handleAddURL]\n    \n    G[导入就绪] --> H[Import Selected 按钮]\n    H --> I[触发导入流程]\n```\n\n文件列表区域使用 `overflow-auto` 支持滚动，导入操作仅在 WebSocket 在线时可用。资料来源：[frontend/app/components/Ingestion/FileSelectionView.tsx:80-120]()\n\n### 基础设置视图\n\nBasicSettingView 组件提供导入文件的详细配置选项，包括 RAG Pipeline 各组件的配置。资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-150]()\n\n**配置项表：**\n\n| 配置项 | 输入类型 | 说明 |\n|-------|---------|------|\n| Source Link | 文本输入 | 文档原始来源链接 |\n| Labels | 标签输入 + 添加按钮 | 文档分类标签 |\n| Chunker | 只读文本 | 分块策略配置 |\n| Embedder | 只读文本 | 嵌入模型配置 |\n| Metadata | Textarea | 键值对元数据 |\n| Overwrite | Checkbox | 是否覆盖同名文档 |\n\n组件使用 `onKeyDown` 事件监听 Enter 键快速添加标签，文本域最大高度限制为 150px。资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:50-100]()\n\n## 设置模块\n\n### 信息视图\n\nInfoView 组件显示系统状态信息和提供重置功能入口。组件从后端 API 获取集群节点信息和 Collection 列表。资料来源：[frontend/app/components/Settings/InfoView.tsx:1-100]()\n\n**信息展示区域表：**\n\n| 区域 | 内容 | 加载状态 |\n|-----|------|---------|\n| Nodes | 节点名称、状态、分片数 | loading-dots |\n| Collections | 集合名称、对象数量 | loading-dots |\n\nInfoView 提供四种重置操作，分别通过 UserModalComponent 组件确认后执行：\n\n1. **Reset Documents**：清除所有文档和分块\n2. **Reset Config**：重置配置\n3. **Reset Verba**：删除 Verba 相关 Collection\n4. **Reset Suggestions**：清除自动完成建议\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:90-120]()\n\n## 登录与初始化\n\n### 登录视图\n\nLoginView 组件处理应用初始化和部署类型选择。根据 `production` 环境变量显示不同界面：资料来源：[frontend/app/components/Login/LoginView.tsx:1-80]()\n\n**部署类型选择表：**\n\n| 部署类型 | 图标 | 说明 |\n|---------|------|------|\n| Weaviate | FaDatabase | 连接 Weaviate 服务 |\n| Docker | FaDocker | Docker 部署模式 |\n| Custom | TbDatabaseEdit | 自定义部署 |\n| Local | FaLaptopCode | 本地开发模式 |\n\n组件使用 `isConnecting` 状态管理连接中动画，通过 `setSelectedDeployment` 回调传递选择结果。资料来源：[frontend/app/components/Login/LoginView.tsx:50-70]()\n\n### 入门引导\n\nGettingStartedComponent 组件在首次使用时显示引导界面，包含项目介绍和缩略图展示。用户点击 \"Let's get started\" 按钮后通过 localStorage 记录已显示状态。资料来源：[frontend/app/components/Login/GettingStarted.tsx:1-60]()\n\n## 主页面结构\n\npage.tsx 作为应用的根组件，组合所有子组件并管理全局状态。主要功能包括：资料来源：[frontend/app/page.tsx:1-100]()\n\n1. **生产环境检测**：根据 `NEXT_PUBLIC_VERBA_PRODUCTION` 环境变量决定显示模式\n2. **组件挂载**：在生产环境下挂载 Navbar 和主内容区域\n3. **底部信息**：显示构建信息和版权声明\n4. **追踪像素**：集成 Scarf 分析工具\n\n```mermaid\ngraph TD\n    A[page.tsx] --> B{production 环境}\n    B -->|Demo| C[隐藏导航栏]\n    B -->|非 Demo| D[显示 NavbarComponent]\n    D --> E[显示主内容区域]\n    E --> F[Footer + 追踪像素]\n    \n    G[GettingStarted 检测] --> H{localStorage}\n    H -->|首次| I[显示引导弹窗]\n    H -->|非首次| J[跳过]\n```\n\n## 数据流与状态管理\n\n### 组件间通信模式\n\nVerba 前端采用以下状态管理模式：\n\n| 模式 | 使用场景 | 示例 |\n|-----|---------|------|\n| Props 向下传递 | 父子组件数据共享 | ChatMessage 接收 message prop |\n| useState | 组件内部状态 | selectedFileData, currentPage |\n| useRef | 可变引用避免重渲染 | isFetching |\n| 回调函数向上传递 | 子向父组件通信 | setCurrentPage, setSelectedDocument |\n\n### API 通信\n\n前端通过 `frontend/app/api.ts` 定义的 API 函数与后端通信，包括：\n\n- 认证与部署配置\n- 文档操作（CRUD）\n- RAG 配置获取与更新\n- 系统状态查询\n\nWebSocket 连接用于实时聊天消息传输和导入进度更新。\n\n## 样式系统\n\n### Verba 主题变量\n\n应用定义了统一的颜色变量系统，以 `-verba` 后缀区分：\n\n| 变量类名 | 用途 |\n|---------|------|\n| text-text-verba | 主文本颜色 |\n| text-text-alt-verba | 次要文本颜色 |\n| bg-bg-verba | 主背景色 |\n| bg-bg-alt-verba | 次要背景色 |\n| bg-primary-verba | 主色调 |\n| bg-button-verba | 按钮默认色 |\n| bg-button-hover-verba | 按钮悬停色 |\n| bg-warning-verba | 警告/错误色 |\n\n资料来源：[frontend/app/components/Chat/ChatMessage.tsx:20-30](), [frontend/app/components/Settings/InfoView.tsx:1-50]()\n\n### 响应式设计\n\n应用采用移动优先的响应式设计策略：\n\n| 断点 | 标识 | 适用场景 |\n|-----|------|---------|\n| < 768px | 默认/sm | 移动端导航、隐藏元素 |\n| ≥ 768px | md | 桌面端导航显示、汉堡菜单隐藏 |\n| ≥ 1024px | lg | 大屏布局调整 |\n\n## 总结\n\nVerba 前端采用组件化、模块化的架构设计，通过清晰的功能划分实现聊天、文档管理、数据导入和系统设置等核心功能。组件间通过 props、回调函数和 React Hooks 进行状态管理，样式系统基于 Tailwind CSS 和 daisyUI 提供一致的用户体验。\n\n---\n\n<a id='page-backend-components'></a>\n\n## 后端组件系统\n\n### 相关页面\n\n相关主题：[系统整体架构](#page-architecture), [模型集成](#page-model-integration), [数据导入与处理](#page-data-ingestion)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [goldenverba/components/interfaces.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/interfaces.py)\n- [goldenverba/components/managers.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/managers.py)\n- [goldenverba/components/types.py](https://github.com/weave/Verba/blob/main/goldenverba/components/types.py)\n- [goldenverba/components/__init__.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/__init__.py)\n- [goldenverba/verba_manager.py](https://github.com/weaviate/Verba/blob/main/goldenverba/verba_manager.py)\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- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n</details>\n\n# 后端组件系统\n\nVerba 是一个开源的 RAG（检索增强生成）应用，其后端采用模块化的组件系统设计。该系统通过标准化的接口定义和统一的管理机制，支持多种 Reader（读取器）、Embedder（嵌入器）、Generator（生成器）和 Retriever（检索器）的灵活组合与配置。\n\n## 系统架构概述\n\nVerba 的后端组件系统基于 Python 实现，采用面向接口的编程范式。核心组件类型包括：\n\n| 组件类型 | 功能描述 | 支持的提供商示例 |\n|---------|---------|-----------------|\n| Reader | 文档读取与解析 | AssemblyAI、URL Reader、Default Reader |\n| Embedder | 文本向量化嵌入 | Ollama、OpenAI、Upstage |\n| Generator | LLM 响应生成 | OpenAI、Anthropic、Cohere、Novita、Upstage、Groq |\n| Retriever | 语义检索功能 | Weaviate 原生检索 |\n\n该系统通过 `goldenverba/components/` 目录下的模块进行组织，所有组件均实现统一的接口规范，从而保证系统的可扩展性和可维护性。资料来源：[setup.py:1-15]()\n\n## 核心类型定义\n\n### Document 数据模型\n\nDocument 是系统中最核心的数据单元，用于表示待处理的文档或文本内容：\n\n```python\nDocument(\n    title=str,           # 文档标题\n    content=str,         # 文档内容\n    extension=str,       # 文件扩展名\n    labels=list,         # 标签列表\n    source=str,          # 原始来源链接\n    fileSize=str,        # 文件大小\n    metadata=dict,       # 元数据\n    meta=dict            # 配置元数据\n)\n```\n\n文档创建可通过 `create_document()` 函数完成，该函数接收文件内容 `content` 和 `FileConfig` 配置对象，返回完整的 Document 实例。资料来源：[goldenverba/components/document.py:40-49]()\n\n### FileConfig 配置模型\n\nFileConfig 用于配置单个文件的导入设置：\n\n```python\nFileConfig(\n    filename=str,        # 文件名\n    extension=str,       # 扩展名\n    labels=list,         # 文件标签\n    source=str,          # 来源链接\n    file_size=str,       # 文件大小\n    metadata=str,        # 元数据字符串\n)\n```\n\n### 组件类型枚举\n\n系统定义了标准化的组件类型枚举，用于区分不同功能的组件：\n\n| 枚举值 | 组件类型 | 用途 |\n|-------|---------|------|\n| `READER` | 读取器 | 解析和加载各种格式的文档 |\n| `EMBEDDER` | 嵌入器 | 将文本转换为向量表示 |\n| `GENERATOR` | 生成器 | 调用 LLM 生成响应 |\n| `RETRIEVER` | 检索器 | 执行语义检索操作 |\n\n## 组件接口规范\n\nVerba 采用面向接口的设计原则，所有组件必须实现相应的抽象接口。接口定义确保了组件之间的解耦，使得添加新的提供商实现变得简单高效。\n\n### 组件生命周期\n\n```mermaid\ngraph TD\n    A[初始化组件] --> B[加载配置]\n    B --> C[建立连接]\n    C --> D[执行操作]\n    D --> E[返回结果]\n    E --> F[释放资源]\n```\n\n组件的典型生命周期包括：初始化、配置加载、连接建立、执行具体操作、结果返回和资源释放。每一步都遵循统一的错误处理机制。\n\n## 环境变量配置\n\nVerba 支持通过环境变量配置组件行为，以下是主要配置项：\n\n| 环境变量 | 用途 | 说明 |\n|---------|------|------|\n| `DEFAULT_DEPLOYMENT` | 部署类型 | 可设为 Local、Docker、Weaviate 或 Custom |\n| `OLLAMA_MODEL` | Ollama 模型 | 指定 Ollama 使用的模型名称 |\n| `OLLAMA_EMBED_MODEL` | Ollama 嵌入模型 | 指定 Ollama 嵌入使用的模型 |\n| `PORT` | 服务端口 | 自定义 Verba 服务监听端口 |\n\n这些环境变量允许用户在启动前预先配置组件，减少前端交互中的配置负担。资料来源：[CHANGELOG.md:8-12]()\n\n## 支持的组件提供商\n\n### 已集成的生成器\n\n| 提供商 | 说明 | 资料来源 |\n|-------|------|---------|\n| OpenAI | GPT 系列模型 | setup.py |\n| Anthropic | Claude 系列模型 | LoginView.tsx |\n| Cohere | Command R 系列 | LoginView.tsx |\n| Upstage | 韩国 Upstage AI | CHANGELOG.md |\n| Novita | Novita AI 服务 | CHANGELOG.md |\n| Groq | Groq 云服务 | CHANGELOG.md |\n\n### 已集成的嵌入器\n\n系统支持多种嵌入模型集成，包括本地 Ollama 模型和云服务提供商的模型。通过统一接口封装，切换不同的嵌入提供商只需修改配置而无需更改业务代码。\n\n### 已集成的读取器\n\n| 读取器 | 支持格式 | 说明 |\n|-------|---------|------|\n| DefaultReader | csv、xlsx、xls、txt 等 | 默认文档读取器 |\n| AssemblyAI | 音频文件 | 通过 AssemblyAI 服务转录音频 |\n| URL Reader | 网页内容 | 从 URL 抓取网页文本 |\n\n版本 2.1.3 新增了对 CSV、Excel 格式的原生支持，扩展了文档处理的覆盖范围。资料来源：[CHANGELOG.md:12]()\n\n## 组件管理器\n\n组件管理器（Managers）负责组件的注册、发现和生命周期管理。它维护了系统中所有可用组件的目录，并提供组件实例化、配置更新和状态监控的功能。\n\n```mermaid\ngraph LR\n    A[前端请求] --> B[Verba Manager]\n    B --> C[组件选择]\n    C --> D[配置应用]\n    D --> E[组件执行]\n    E --> F[结果返回]\n```\n\n### 管理器核心职责\n\n- **组件注册**：将新组件注册到系统中\n- **配置管理**：维护各组件的配置状态\n- **依赖解析**：处理组件间的依赖关系\n- **资源分配**：管理组件使用的计算资源\n\n## 部署模式与组件关系\n\nVerba 支持四种部署模式，不同模式下启用的组件有所不同：\n\n| 部署模式 | 特性 | 适用场景 |\n|---------|------|---------|\n| Local | 本地 Ollama 或远程 LLM | 开发测试 |\n| Docker | 容器化部署 | 生产环境 |\n| Weaviate | Weaviate Cloud | 云端托管 |\n| Custom | 自定义 Weaviate 实例 | 企业内部部署 |\n\n在 Demo 模式下，部分管理功能（如 Import Data、Settings）会被隐藏，仅保留核心的 Chat 功能。资料来源：[NavbarComponent.tsx:15-30]()\n\n## 前端配置交互\n\n前端通过标准化接口与后端组件系统交互，主要涉及以下配置文件：\n\n```typescript\ninterface RAGConfig {\n    \"Reader\": { components: Record<string, ComponentConfig> };\n    \"Embedder\": { components: Record<string, ComponentConfig> };\n    \"Generator\": { components: Record<string, ComponentConfig> };\n    \"Retriever\": { components: Record<string, ComponentConfig> };\n}\n```\n\n前端组件如 `ChatConfig.tsx` 负责渲染各组件的配置界面，用户可以动态选择和配置 Reader、Embedder、Generator 和 Retriever。资料来源：[ChatConfig.tsx:20-40]()\n\n## 版本演进\n\n| 版本 | 主要变更 |\n|------|---------|\n| 2.1.3 | 新增 OLLAMA 环境变量支持；扩展 DefaultReader 支持 xlsx/xls/csv |\n| 2.1.2 | 新增 Novita 生成器；添加文档类基础测试 |\n| 2.1.1 | 动态模型名称获取 |\n| 2.1.0 | 新增 Upstage 全套组件；Groq 集成；AssemblyAI 音频读取器 |\n\n组件系统的持续演进体现了 Verba 对多提供商支持和格式兼容性的重视。\n\n## 开发指南\n\n### 添加新组件\n\n1. 在 `goldenverba/components/` 下创建新的组件文件\n2. 实现统一的组件接口\n3. 在组件管理器中注册新组件\n4. 在前端添加对应的配置界面\n\n### 配置验证\n\n系统启动时会验证环境变量和 API Key 的有效性。建议使用 `.env` 文件集中管理敏感配置，Verba 会自动读取并应用这些配置。\n\n---\n\n<a id='page-data-ingestion'></a>\n\n## 数据导入与处理\n\n### 相关页面\n\n相关主题：[后端组件系统](#page-backend-components), [RAG 检索与生成流程](#page-rag-pipeline), [环境变量与配置](#page-configuration)\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- [frontend/app/components/Ingestion/FileSelectionView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/FileSelectionView.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/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n- [frontend/app/components/Document/ChunkView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Document/ChunkView.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# 数据导入与处理\n\n## 概述\n\nVerba 的数据导入与处理模块是 RAG（检索增强生成）流水线的核心入口，负责将各类数据源（文件、目录、URL）摄入系统并进行预处理。该模块支持多种文件格式的读取、文档分块（Chunking）、向量化（Embedding）等关键步骤，最终将处理后的数据存储至 Weaviate 向量数据库中。\n\n从 CHANGELOG.md 的记录可知，Verba 2.1.3 版本已添加对 `csv`、`xlsx`、`xls` 格式的支持，显著扩展了数据导入的灵活性。资料来源：[CHANGELOG.md:10-12]()\n\n## 核心架构\n\nVerba 的数据处理采用模块化 RAG 配置架构，每个文档可独立配置 Reader、Chunker、Embedder 组件。这种设计允许用户根据不同数据类型选择最优的处理策略。\n\n```mermaid\ngraph TD\n    A[用户导入数据] --> B[Reader 组件]\n    B --> C[Chunker 分块]\n    C --> D[Embedder 向量化]\n    D --> E[Weaviate 存储]\n    \n    F[文件/目录/URL] --> B\n    G[元数据配置] --> E\n    H[标签管理] --> E\n```\n\n## 数据导入流程\n\n### 导入方式\n\nVerba 前端界面提供了三种数据导入方式，分别对应不同的使用场景：\n\n| 导入方式 | 适用场景 | 处理逻辑 |\n|---------|---------|---------|\n| Add Files | 单文件或少量文件上传 | 直接读取文件内容 |\n| Add Directory | 批量导入文件夹 | 遍历目录下的所有支持文件 |\n| Add URL | 网页内容抓取 | 通过 URL Reader 解析网页 |\n\n资料来源：[README.md:28-32]()\n\n### 导入界面组件\n\n前端 `NavbarComponent.tsx` 中的导航栏提供了 \"Import Data\" 入口，该入口仅在非 Demo 模式下显示：\n\n```typescript\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\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:45-54]()\n\n## 文件配置选项\n\n在 `BasicSettingView.tsx` 中，Verba 提供了丰富的文件配置选项，每个文件可独立设置以下参数：\n\n### 基本信息配置\n\n| 配置项 | 说明 | 数据类型 |\n|-------|------|---------|\n| Title | 文档标题 | 字符串 |\n| Source Link | 原始数据来源链接 | URL 字符串 |\n| Labels | 文档标签，用于分类检索 | 字符串数组 |\n| Metadata | 元数据，影响检索和生成结果 | JSON 字符串 |\n| Overwrite | 是否覆盖同名文档 | 布尔值 |\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:28-70]()\n\n### 标签管理\n\n用户可以通过输入框添加标签，按 Enter 键或点击 Add 按钮即可添加标签到当前文档：\n\n```typescript\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```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:36-48]()\n\n### 元数据配置\n\n元数据以 JSON 格式存储，会被添加到发送给 Embedder 和 Generator 的上下文中，从而影响检索和生成结果：\n\n```typescript\n<textarea\n  className=\"grow w-full textarea flex items-center gap-2 max-h-64 bg-bg-verba\"\n  value={metadata}\n  onChange={handleMetadataChange}\n/>\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:93-98]()\n\n## RAG 组件配置\n\n每个导入的文件都可以独立配置其 RAG 流水线中的关键组件：\n\n### Chunker 分块器\n\n用于将长文档切分为适合检索的较小单元。分块策略直接影响后续检索的质量和上下文完整性。\n\n### Embedder 向量化器\n\n负责将文本内容转换为向量表示，存储至 Weaviate 以支持语义检索。\n\n```typescript\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:148-160]()\n\n## 文档对象模型\n\n`Document` 类是 Verba 中数据表示的核心结构，定义在 `goldenverba/components/document.py` 中：\n\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资料来源：[goldenverba/components/document.py:56-68]()\n\nDocument 对象包含以下核心字段：\n\n| 字段 | 说明 |\n|-----|------|\n| title | 文档标题 |\n| content | 文档原始内容 |\n| extension | 文件扩展名 |\n| labels | 标签数组 |\n| source | 来源链接 |\n| fileSize | 文件大小 |\n| metadata | 元数据字符串 |\n| chunks | 分块后的数据列表 |\n\n## 分块查看器\n\n导入后的文档可以通过 Document Explorer 查看其分块内容。`ChunkView.tsx` 组件负责渲染和导航分块：\n\n```typescript\n<div className=\"flex gap-2 items-center p-3 bg-secondary-verba rounded-full w-fit\">\n  <IoNewspaper size={12} />\n  <p className=\"text-xs flex text-text-verba\">\n    Chunk {chunks[currentChunkIndex].chunk_id}\n  </p>\n</div>\n```\n\n资料来源：[frontend/app/components/Document/ChunkView.tsx:28-34]()\n\n### 分块导航\n\n支持 Previous 和 Next 按钮进行分块间的导航切换：\n\n```typescript\n<VerbaButton\n  title={\"Previous \" + (chunkScores ? \"Chunk\" : \"Page\")}\n  onClick={previousPage}\n/>\n<VerbaButton\n  title={\"Next \" + (chunkScores ? \"Chunk\" : \"Page\")}\n  onClick={nextPage}\n/>\n```\n\n资料来源：[frontend/app/components/Document/ContentView.tsx:52-68]()\n\n## 文件导入流程图\n\n```mermaid\ngraph LR\n    A[选择导入方式] --> B{导入类型}\n    B -->|文件| C[上传文件]\n    B -->|目录| D[选择目录]\n    B -->|URL| E[输入URL]\n    \n    C --> F[配置Reader组件]\n    D --> F\n    E --> F\n    \n    F --> G[配置Chunker]\n    G --> H[配置Embedder]\n    H --> I[设置元数据]\n    \n    I --> J[点击Import Selected]\n    J --> K[后端处理]\n    K --> L[存入Weaviate]\n    L --> M[导入完成]\n```\n\n## 环境变量配置\n\nVerba 支持通过 `.env` 文件预配置导入相关的环境变量，无需在界面中重复输入：\n\n| 环境变量 | 说明 |\n|---------|------|\n| OLLAMA_MODEL | Ollama 使用的模型名称 |\n| OLLAMA_EMBED_MODEL | Ollama 嵌入模型名称 |\n\n资料来源：[CHANGELOG.md:8-9]()\n\n## 依赖项\n\n数据导入模块依赖以下核心 Python 包，定义在 `setup.py` 中：\n\n| 包名 | 版本 | 用途 |\n|-----|------|-----|\n| weaviate-client | 4.9.6 | 向量数据库交互 |\n| openpyxl | 3.1.5 | Excel 文件处理 |\n| xlrd | 2.0.1 | 旧版 Excel 读取 |\n\n资料来源：[setup.py:18-23]()\n\n## 最佳实践\n\n### 文件命名\n\n建议为文档设置有意义的标题，便于后续在 Document Explorer 中识别和检索。系统会自动为 URL 类型的内容使用其 URL 作为默认文件名。\n\n### 元数据使用\n\n合理使用元数据可以显著提升检索精度。元数据会被添加到上下文请求中，影响嵌入和生成结果。建议添加文档来源、时间、作者等关键信息。\n\n### 标签管理\n\n使用一致的标签体系有助于组织大量文档。标签可用于快速过滤和分组相关文档。\n\n### 分块策略选择\n\n根据文档类型选择合适的分块策略。长文档建议使用语义分块（Semantic Chunking），短文档可使用固定长度分块。\n\n---\n\n<a id='page-rag-pipeline'></a>\n\n## RAG 检索与生成流程\n\n### 相关页面\n\n相关主题：[模型集成](#page-model-integration), [数据导入与处理](#page-data-ingestion), [前端架构与组件](#page-frontend-structure)\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- [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- [frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.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/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n- [frontend/app/components/Settings/InfoView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Settings/InfoView.tsx)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n</details>\n\n# RAG 检索与生成流程\n\n## 概述\n\nVerba 是一个开源的 RAG（Retrieval-Augmented Generation，检索增强生成）应用，名为 \"Golden RAGtriever\"。该项目由 Weaviate 团队开发，旨在为检索增强生成应用提供流线型、用户友好的界面。Verba 允许用户通过几个简单步骤深入数据并进行有意义的交互。\n\nRAG 流程是 Verba 的核心功能，它将文档检索与语言模型生成相结合，使用户能够针对自己的数据提出问题并获得基于上下文的答案。\n\n## 系统架构\n\n```mermaid\ngraph TD\n    A[用户提问] --> B[Chat Interface]\n    B --> C{检索阶段}\n    C --> D[Embedder 嵌入向量]\n    D --> E[Weaviate 向量数据库]\n    E --> F[Retriever 检索相关 Chunk]\n    F --> G{生成阶段}\n    G --> H[Generator 生成模型]\n    H --> I[返回答案与上下文]\n    \n    J[数据导入] --> K[Reader 读取文件]\n    K --> L[Chunker 分块处理]\n    L --> M[Embedder 向量化]\n    M --> E\n```\n\n## 核心组件\n\n### 组件配置架构\n\nVerba 的 RAG 管道由三个核心组件构成，通过 `ChatConfig` 组件进行统一配置管理：\n\n| 组件类型 | 功能描述 | 配置位置 |\n|---------|---------|---------|\n| **Embedder** | 将文本转换为向量嵌入 | 检索阶段 |\n| **Retriever** | 从向量数据库检索相关文档块 | 检索阶段 |\n| **Generator** | 基于检索结果生成最终答案 | 生成阶段 |\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:33-48]()\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<ComponentView\n  RAGConfig={RAGConfig}\n  component_name=\"Generator\"\n  selectComponent={selectComponent}\n  updateConfig={updateConfig}\n  saveComponentConfig={saveComponentConfig}\n  blocked={production == \"Demo\"}\n/>\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## 检索流程详解\n\n### 向量化与存储\n\n用户导入的文档经过以下处理流程进入系统：\n\n1. **文档读取**：通过 Reader 组件读取多种格式的文件（包括 `csv`、`xlsx`、`xls` 等）\n2. **文档创建**：使用 `Document` 类封装文档元数据\n3. **分块处理**：将文档切分为适合检索的文本块（Chunks）\n4. **向量化存储**：通过 Embedder 将文本块转换为向量，存储于 Weaviate 向量数据库\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:60-70]()\n资料来源：[goldenverba/components/document.py:42-53]()\n\n### 检索过程\n\n```mermaid\ngraph LR\n    A[用户问题] --> B[Query 向量化]\n    B --> C[向量相似度搜索]\n    C --> D[Top-K 检索]\n    D --> E[返回相关 Chunks]\n    E --> F[传递给 Generator]\n```\n\n当用户在 Chat 界面输入问题时，系统执行以下步骤：\n\n1. **问题向量化**：用户输入的查询文本通过 Embedder 转换为查询向量\n2. **向量搜索**：在 Weaviate 中执行向量相似度搜索\n3. **结果排序**：根据相似度得分返回最相关的 K 个文档块\n4. **状态展示**：前端显示 \"Retrieving...\" 状态提示\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:8-15]()\n\n```tsx\n<p className=\"text-text-alt-verba\">\n  {fetchingStatus === \"CHUNKS\" && \"Retrieving...\"}\n  {fetchingStatus === \"RESPONSE\" && \"Generating...\"}\n</p>\n```\n\n## 生成流程详解\n\n### 上下文增强的生成\n\n检索到的文档块（Chunks）与用户问题一起作为上下文传递给 Generator 组件：\n\n```mermaid\ngraph TD\n    A[用户问题] --> E\n    B[检索到的 Chunks] --> E\n    E[上下文组装] --> F[Prompt 构建]\n    F --> G[LLM 生成]\n    G --> H[返回答案]\n```\n\nGenerator 组件支持多种大语言模型提供者，包括：\n\n- **OpenAI**（支持动态模型名称获取）\n- **Ollama**（支持 `OLLAMA_MODEL` 和 `OLLAMA_EMBED_MODEL` 环境变量配置）\n- **Novita**\n- **Upstage**\n- **Groq**\n- **Anthropic**（通过 Ollama 或 LLM 提供商）\n\n资料来源：[CHANGELOG.md:6-15]()\n\n### 响应状态管理\n\n生成过程中的状态通过 `fetchingStatus` 状态机管理：\n\n| 状态值 | 含义 | UI 显示 |\n|-------|------|--------|\n| `IDLE` | 空闲状态 | 正常输入框 |\n| `CHUNKS` | 正在检索文档块 | \"Retrieving...\" |\n| `RESPONSE` | 正在生成响应 | \"Generating...\" |\n| `DONE` | 完成 | 显示结果 |\n\n用户可以通过取消按钮随时终止检索或生成过程：\n\n```tsx\n<button\n  onClick={() => {\n    setFetchingStatus(\"DONE\");\n    isFetching.current = false;\n  }}\n  className=\"btn btn-circle btn-sm bg-bg-alt-verba hover:bg-warning-verba...\"\n>\n  <MdCancel size={15} />\n</button>\n```\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:16-24]()\n\n## 数据模型\n\n### Document 类结构\n\n```python\nclass Document:\n    def __init__(\n        self,\n        title: str,           # 文档标题\n        content: str,         # 文档内容\n        extension: str,       # 文件扩展名\n        labels: List[str],    # 标签列表\n        source: str,          # 源链接\n        fileSize: int,        # 文件大小\n        metadata: str,        # 元数据\n        meta: Dict,           # 额外元数据\n    )\n```\n\n文档对象在导入时通过 `create_document` 函数创建，该函数将文件内容与 `FileConfig` 配置结合生成完整的文档对象。\n\n资料来源：[goldenverba/components/document.py:1-53]()\n\n### 文件配置结构\n\n导入文件时，系统为每个文件维护独立的配置状态：\n\n```tsx\ninterface FileData {\n  content: string;           // 文件内容\n  rag_config: RAGConfig;     // RAG 组件配置\n  block: boolean;            // 是否阻塞\n  filename: string;         // 文件名/标题\n  source: string;           // 源链接\n  labels: string[];         // 标签\n  metadata: object;         // 元数据\n}\n```\n\n每个文件可以独立配置 Reader、Embedder、Generator 等组件，实现灵活的管道定制。\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-80]()\n\n## 部署模式\n\nVerba 支持多种部署方式，RAG 流程的配置也会相应调整：\n\n| 部署模式 | 说明 | RAG 配置限制 |\n|---------|------|-------------|\n| **Local** | 本地 Weaviate 实例 | 完全可配置 |\n| **Docker** | Docker 容器部署 | 完全可配置 |\n| **Weaviate Cloud** (WCS) | 云端托管服务 | 完全可配置 |\n| **Custom** | 自定义 Weaviate 实例 | 完全可配置 |\n| **Demo** | 演示模式 | 配置不可修改 |\n\n可通过 `DEFAULT_DEPLOYMENT` 环境变量设置默认部署类型。\n\n资料来源：[frontend/app/components/Login/LoginView.tsx:15-30]()\n资料来源：[README.md:1-30]()\n\n## 用户交互界面\n\n### 导航与页面结构\n\nVerba 前端采用单页应用架构，主要导航入口包括：\n\n```mermaid\ngraph TD\n    A[Navbar] --> B[Chat 页面]\n    A --> C[Documents 页面]\n    A --> D[Import Data 页面]\n    A --> E[Settings 页面]\n    \n    B --> B1[对话输入]\n    B --> B2[聊天历史]\n    B --> B3[配置面板]\n    \n    C --> C1[文档列表]\n    C --> C2[内容查看器]\n    C --> C3[向量可视化]\n```\n\n导航组件根据部署环境动态显示菜单项：\n\n```tsx\n{production != \"Demo\" && (\n  <li key={\"Menu Button4\"}>\n    <a onClick={() => setCurrentPage(\"ADD\")}>Import Data</a>\n  </li>\n)}\n```\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:1-50]()\n\n### 文档浏览与 Chunk 导航\n\n在 Documents 页面中，用户可以浏览已导入的文档内容，并按 Chunk 分页查看：\n\n```tsx\n<VerbaButton\n  title={\"Previous \" + (chunkScores ? \"Chunk\" : \"Page\")}\n  onClick={previousPage}\n/>\n<p className=\"text-xs text-text-verba\">\n  {chunkScores ? \"Chunk \" : \"Page \"} {page}\n</p>\n<VerbaButton\n  title={\"Next \" + (chunkScores ? \"Chunk\" : \"Page\")}\n  onClick={nextPage}\n/>\n```\n\n资料来源：[frontend/app/components/Document/ContentView.tsx:40-55]()\n\n## 核心技术栈\n\n| 层级 | 技术选型 | 版本要求 |\n|-----|---------|---------|\n| **后端框架** | FastAPI | 0.111.1 |\n| **向量数据库客户端** | weaviate-client | 4.9.6 |\n| **服务器** | Uvicorn + Gunicorn | 0.29.0 / 22.0.0 |\n| **前端框架** | React (Next.js) | - |\n| **UI 组件库** | daisyUI + Tailwind CSS | - |\n| **Python 版本** | 3.10 - 3.12 | - |\n\n资料来源：[setup.py:1-30]()\n\n## 配置管理\n\n### 运行时配置重置\n\nSettings 页面提供多种重置功能，用于管理 RAG 系统状态：\n\n| 功能 | 说明 | 影响范围 |\n|-----|------|---------|\n| **Reset Documents** | 清除所有文档和 Chunk | 文档数据 |\n| **Reset Config** | 重置 RAG 组件配置 | 配置状态 |\n| **Reset Verba** | 删除所有 Verba 相关集合 | 全部数据 |\n| **Reset Suggestions** | 清除自动补全建议 | 用户偏好 |\n\n```tsx\n<UserModalComponent\n  modal_id=\"reset-documents\"\n  title=\"Reset Documents\"\n  text=\"Are you sure you want to reset all documents? This will clear all documents and chunks from Verba.\"\n  triggerAccept={resetDocuments}\n  triggerString=\"Reset\"\n/>\n```\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:1-50]()\n\n## 总结\n\nVerba 的 RAG 检索与生成流程是一个端到端的智能问答系统：\n\n1. **数据导入阶段**：文档通过 Reader 读取、Chunker 分块、Embedder 向量化后存入 Weaviate\n2. **检索阶段**：用户问题通过 Embedder 向量化，在向量数据库中执行相似度搜索返回相关 Chunks\n3. **生成阶段**：检索结果与问题组装为 Prompt，传递给 Generator（LLM）生成最终答案\n4. **展示阶段**：答案与相关上下文在 Chat 界面展示，支持用户继续交互\n\n整个流程高度可配置，支持多种部署模式和多种大语言模型提供商，满足不同场景下的 RAG 应用需求。\n\n---\n\n<a id='page-model-integration'></a>\n\n## 模型集成\n\n### 相关页面\n\n相关主题：[后端组件系统](#page-backend-components), [RAG 检索与生成流程](#page-rag-pipeline), [环境变量与配置](#page-configuration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\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/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.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/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- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n</details>\n\n# 模型集成\n\n## 概述\n\n模型集成是 Verba（Golden RAGtriever）系统的核心功能模块，负责管理和协调 RAG（检索增强生成）管道中的三类关键组件：**嵌入模型（Embedder）**、**生成模型（Generator）** 和 **检索器（Retriever）**。通过标准化的组件接口设计，Verba 支持灵活接入多种大语言模型提供商和嵌入服务，实现端到端的向量检索与生成式问答功能。\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:35-45]()\n\n## 架构设计\n\n### 组件层次结构\n\nVerba 的模型集成采用模块化架构，各组件通过统一的配置接口进行管理：\n\n```mermaid\ngraph TD\n    subgraph \"RAG 配置层\"\n        RAGConfig[RAGConfig 配置对象]\n    end\n    \n    subgraph \"嵌入层 Embedder\"\n        OpenAI_Emb[OpenAI Embedder]\n        Cohere_Emb[Cohere Embedder]\n        Ollama_Emb[Ollama Embedder]\n    end\n    \n    subgraph \"生成层 Generator\"\n        OpenAI_Gen[OpenAI Generator]\n        Anthropic_Gen[Anthropic Generator]\n        Gemini_Gen[Gemini Generator]\n        Groq_Gen[Groq Generator]\n        Novita_Gen[Novita Generator]\n        Upstage_Gen[Upstage Generator]\n    end\n    \n    subgraph \"检索层 Retriever\"\n        BM25_R[BM25 Retriever]\n        Vector_R[Vector Retriever]\n        Hybrid_R[Hybrid Retriever]\n    end\n    \n    RAGConfig --> OpenAI_Emb\n    RAGConfig --> OpenAI_Gen\n    RAGConfig --> BM25_R\n    \n    style RAGConfig fill:#f9f,stroke:#333,stroke-width:2px\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:50-60]()\n\n### 集成流程\n\n模型集成的完整工作流程包括配置选择、内容处理、向量嵌入和生成响应四个阶段：\n\n```mermaid\ngraph LR\n    A[用户选择组件配置] --> B[加载嵌入模型]\n    B --> C[加载生成模型]\n    C --> D[文档分块 Chunker]\n    D --> E[向量嵌入 Embedding]\n    E --> F[存储至向量数据库]\n    F --> G[用户查询]\n    G --> H[检索相关块]\n    H --> I[上下文组装]\n    I --> J[生成响应]\n```\n\n## 支持的模型提供商\n\n### 嵌入模型（Embedder）\n\nVerba 支持多种嵌入模型服务，通过 `OLLAMA_EMBED_MODEL` 等环境变量进行配置。\n\n| 提供商 | 类型 | 配置方式 | 状态 |\n|--------|------|----------|------|\n| OpenAI | Embedder | API Key + Model Name | 稳定 |\n| Cohere | Embedder | API Key + Model Name | 稳定 |\n| Ollama | Embedder | 本地模型 + URL | 稳定 |\n| Upstage | Embedder | API Key + Model Name | 稳定 |\n\n资料来源：[CHANGELOG.md:7-8]()\n\n### 生成模型（Generator）\n\n生成器组件支持多种大语言模型提供商，系统会根据 API 凭证动态获取模型名称。\n\n| 提供商 | 组件类 | 特点 | 添加版本 |\n|--------|--------|------|----------|\n| OpenAI | OpenAI Generator | 动态模型名称获取 | 稳定 |\n| Anthropic | Anthrophic Generator | 支持 Claude 系列 | 稳定 |\n| Gemini | Gemini Generator | Google 生成式 AI | 稳定 |\n| Groq | Groq Generator | 低延迟推理 | 2.1.0+ |\n| Novita | Novita Generator | 新型提供商 | 2.1.2+ |\n| Upstage | Upstage Generator | 综合型解决方案 | 2.1.0+ |\n\n资料来源：[CHANGELOG.md:15-16]()\n\n### 检索器（Retriever）\n\n检索器负责从向量数据库中获取相关内容，支持多种检索策略。\n\n## 配置管理\n\n### RAGConfig 结构\n\nRAGConfig 是管理所有组件配置的核心对象，采用组件名称作为键值：\n\n```typescript\ninterface RAGConfig {\n  \"Embedder\": {\n    selected: string;          // 当前选中的嵌入器名称\n    components: {\n      [key: string]: {\n        name: string;\n        type: string;\n        description: string;\n        models?: string[];    // 可用模型列表\n      }\n    }\n  };\n  \"Generator\": {\n    selected: string;\n    components: {\n      [key: string]: {\n        name: string;\n        type: string;\n        description: string;\n      }\n    }\n  };\n  \"Retriever\": {\n    selected: string;\n    components: {\n      [key: string]: {\n        name: string;\n        type: string;\n        description: string;\n      }\n    }\n  };\n}\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:30-45]()\n\n### 环境变量配置\n\nVerba 支持通过环境变量配置模型集成参数：\n\n| 环境变量 | 用途 | 示例值 |\n|----------|------|--------|\n| `OLLAMA_MODEL` | Ollama 生成模型 | `llama2` |\n| `OLLAMA_EMBED_MODEL` | Ollama 嵌入模型 | `nomic-embed-text` |\n| `OPENAI_API_KEY` | OpenAI API 密钥 | `sk-...` |\n| `ANTHROPIC_API_KEY` | Anthropic API 密钥 | `sk-ant-...` |\n\n资料来源：[CHANGELOG.md:7-8]()\n\n## 前端配置界面\n\n### ChatConfig 组件\n\nChatConfig 组件提供交互式界面，用于配置 RAG 管道中的三类核心组件：\n\n```tsx\n<div className=\"flex flex-col justify-start gap-3 rounded-2xl w-full p-6\">\n  <ComponentView\n    RAGConfig={RAGConfig}\n    component_name=\"Embedder\"\n    selectComponent={selectComponent}\n    updateConfig={updateConfig}\n    saveComponentConfig={saveComponentConfig}\n    blocked={production == \"Demo\"}\n  />\n  <ComponentView\n    RAGConfig={RAGConfig}\n    component_name=\"Generator\"\n    selectComponent={selectComponent}\n    updateConfig={updateConfig}\n    saveComponentConfig={saveComponentConfig}\n    blocked={production == \"Demo\"}\n  />\n  <ComponentView\n    RAGConfig={RAGConfig}\n    component_name=\"Retriever\"\n    selectComponent={selectComponent}\n    updateConfig={updateConfig}\n    saveComponentConfig={saveComponentConfig}\n    blocked={production == \"Demo\"}\n  />\n</div>\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:35-55]()\n\n### 组件选择机制\n\n组件选择通过 `selectComponent` 函数处理，该函数更新 `RAGConfig` 中的 `selected` 字段：\n\n```mermaid\nsequenceDiagram\n    participant User as 用户\n    participant UI as ChatConfig UI\n    participant State as 状态管理\n    participant Backend as 后端 API\n    \n    User->>UI: 选择组件下拉菜单\n    UI->>State: 调用 selectComponent()\n    State->>Backend: 更新 RAGConfig\n    Backend-->>State: 返回更新后的配置\n    State-->>UI: 刷新组件视图\n```\n\n### 配置保存与重置\n\n系统提供两种配置操作：\n\n- **保存配置（onSave）**：将当前 RAGConfig 持久化至后端\n- **重置配置（onReset）**：将配置恢复至默认值\n\n```tsx\n<VerbaButton\n  title=\"Save Config\"\n  onClick={onSave}\n  disabled={production == \"Demo\"}\n/>\n<VerbaButton\n  title=\"Reset Config\"\n  onClick={onReset}\n  disabled={production == \"Demo\"}\n/>\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:20-30]()\n\n## 内容处理流程\n\n### 文档导入配置\n\n在文档导入阶段，用户可配置以下处理组件：\n\n| 组件 | 作用 | 配置项 |\n|------|------|--------|\n| **Reader** | 读取文档内容 | 支持 PDF、CSV、XLSX、XLS 等格式 |\n| **Chunker** | 文档分块 | 控制块大小和重叠 |\n| **Embedder** | 向量嵌入 | 生成文档向量表示 |\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-20]()\n\n### 嵌入配置界面\n\n嵌入器配置显示当前选中的嵌入器及其描述信息：\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:60-72]()\n\n### 调试功能\n\n系统提供调试模式，允许用户查看完整的文件配置 JSON：\n\n```tsx\n<div className=\"flex gap-2 justify-between items-center text-text-verba\">\n  <p className=\"flex min-w-[8vw]\">Debug</p>\n  <VerbaButton\n    Icon={CgDebug}\n    onClick={openDebugModal}\n    className=\"max-w-min\"\n  />\n</div>\n```\n\n调试输出会过滤掉 `content` 属性，仅显示配置结构：\n\n```tsx\nconst objCopy = { ...fileMap[selectedFileData] };\nobjCopy.content = \"File Content\";\nreturn JSON.stringify(objCopy, null, 2);\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:95-110]()\n\n## 系统信息展示\n\n### InfoView 组件\n\nInfoView 组件展示当前集成的系统信息，包括连接状态和版本信息：\n\n```tsx\n<div className=\"flex flex-col border-2 gap-2 border-bg-verba shadow-sm p-4 rounded-lg\">\n  <p className=\"text-sm lg:text-base font-semibold text-text-alt-verba\">\n    Connected to\n  </p>\n  <p className=\"text-text-verba\">{credentials.url}</p>\n</div>\n\n<div className=\"flex flex-col border-2 gap-2 border-bg-verba shadow-sm p-4 rounded-lg\">\n  <p className=\"text-sm lg:text-base font-semibold text-text-alt-verba\">\n    Deployment\n  </p>\n  <p className=\"text-text-verba\">{credentials.deployment}</p>\n</div>\n```\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:1-20]()\n\n### 版本信息\n\n系统显示 Weaviate 和 Verba 的版本信息，用于诊断集成问题：\n\n```tsx\n{nodePayload ? (\n  <p className=\"text-text-verba\">{nodePayload.weaviate_version}</p>\n) : (\n  <span className=\"loading loading-spinner loading-sm\"></span>\n)}\n```\n\n## 依赖管理\n\n### Python 依赖\n\nVerba 后端依赖以下核心包实现模型集成：\n\n| 包名 | 版本 | 用途 |\n|------|------|------|\n| `weaviate-client` | 4.9.6 | 向量数据库客户端 |\n| `fastapi` | 0.111.1 | API 服务框架 |\n| `uvicorn` | 0.29.0 | ASGI 服务器 |\n| `openai` | - | OpenAI API 接口 |\n\n资料来源：[setup.py:15-25]()\n\n## 版本更新记录\n\n| 版本 | 更新内容 |\n|------|----------|\n| 2.1.3 | 添加 OLLAMA_MODEL 和 OLLAMA_EMBED_MODEL 环境变量支持 |\n| 2.1.2 | 添加 Novita Generator，修复 spaCy 语言问题 |\n| 2.1.1 | 动态模型名称获取（基于 OpenAI URL 和 API Key） |\n| 2.1.0 | 添加 Upstage、Groq 支持，添加 AssemblyAI Reader |\n\n资料来源：[CHANGELOG.md:1-20]()\n\n## 最佳实践\n\n### 模型选择建议\n\n1. **嵌入模型选择**：根据向量数据库和语料特性选择合适的嵌入维度\n2. **生成模型选择**：考虑延迟、成本和能力平衡\n3. **检索器选择**：混合检索（Hybrid）通常效果最佳\n\n### 配置管理\n\n- 使用环境变量管理敏感凭证\n- 在非 Demo 模式下保存配置以实现持久化\n- 定期检查 CHANGELOG 获取最新支持的功能\n\n---\n\n<a id='page-deployment'></a>\n\n## 部署方式\n\n### 相关页面\n\n相关主题：[环境变量与配置](#page-configuration), [Verba 简介](#page-introduction)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [docker-compose.yml](https://github.com/weaviate/Verba/blob/main/docker-compose.yml)\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- [PYTHON_TUTORIAL.md](https://github.com/weaviate/Verba/blob/main/PYTHON_TUTORIAL.md)\n- [frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n</details>\n\n# 部署方式\n\nVerba（Golden Verba）是一款开源的 RAG（检索增强生成）应用，提供了多种部署方式以满足不同用户的需求。本页面详细介绍 Verba 的四种部署类型、配置方法以及各部署方式的技术细节。\n\n## 部署类型概述\n\nVerba 支持四种主要的部署类型，用户可以在首次启动时通过登录界面进行选择：\n\n| 部署类型 | 说明 | 使用场景 |\n|---------|------|---------|\n| Local | 使用 Weaviate Embedded，在应用内部初始化 Weaviate 实例 | 本地开发、快速原型 |\n| Docker | 在同一 Docker 网络中使用独立的 Weaviate 容器 | 容器化部署、生产环境 |\n| Weaviate Cloud (WCS) | 使用 Weaviate 云服务托管的实例 | 云端托管、无需自行维护 |\n| Custom | 用户自定义 Weaviate 实例 URL、端口和 API Key | 连接现有 Weaviate 基础设施 |\n\n资料来源：[frontend/app/components/Login/LoginView.tsx:55-58]()\n\n```mermaid\ngraph TD\n    A[Verba 部署选择] --> B[Local 部署]\n    A --> C[Docker 部署]\n    A --> D[Weaviate Cloud 部署]\n    A --> E[Custom 部署]\n    \n    B --> B1[Weaviate Embedded]\n    C --> C1[独立 Weaviate 容器]\n    D --> D1[Weaviate Cloud Services]\n    E --> E1[自建 Weaviate 实例]\n```\n\n## 前置要求\n\n### Python 环境要求\n\nVerba 对 Python 版本有明确要求：\n\n| 参数 | 要求 |\n|------|------|\n| Python 版本 | >= 3.10.0, < 3.13.0 |\n| 包管理工具 | pip |\n| 操作系统 | Windows、macOS、Linux |\n\n资料来源：[setup.py:9]()\n\n### 环境变量配置\n\nVerba 支持通过 `.env` 文件自动加载环境变量。建议在项目根目录创建 `.env` 文件，参考 `goldenverba/.env.example` 文件进行配置。\n\n| 环境变量 | 说明 |\n|---------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥 |\n| `COHERE_API_KEY` | Cohere API 密钥 |\n| `WEAVIATE_URL_VERBA` | Weaviate 服务地址 |\n| `OLLAMA_URL` | Ollama 服务地址 |\n| `OLLAMA_MODEL` | Ollama 生成模型 |\n| `OLLAMA_EMBED_MODEL` | Ollama 嵌入模型 |\n| `UNSTRUCTURED_API_KEY` | Unstructured API 密钥 |\n| `UNSTRUCTURED_API_URL` | Unstructured API 地址 |\n| `GITHUB_TOKEN` | GitHub 访问令牌 |\n| `DEFAULT_DEPLOYMENT` | 默认部署类型（Local/Docker/Weaviate/Custom）|\n\n资料来源：[README.md:28-35]()\n\n## 方式一：pip 安装部署\n\n这是最简单快捷的部署方式，适合快速体验 Verba。\n\n### 安装步骤\n\n```bash\n# 1. 创建虚拟环境\npython3 -m virtualenv venv\nsource venv/bin/activate  # Linux/macOS\n# venv\\Scripts\\activate.bat  # Windows\n\n# 2. 安装 Verba\npip install goldenverba\n\n# 3. 启动应用\nverba start\n\n# 4. 访问应用\n# 访问 http://localhost:8000\n```\n\n资料来源：[README.md:40-55]()\n\n### 指定端口和主机\n\n```bash\nverba start --port 8080 --host 0.0.0.0\n```\n\n### 包信息\n\n| 项目 | 值 |\n|------|-----|\n| 包名 | goldenverba |\n| 版本 | 2.1.3 |\n| 入口点 | `verba=goldenverba.server.cli:cli` |\n\n资料来源：[setup.py:1-12]()\n\n## 方式二：从源码构建\n\n适合需要自定义或参与开发的用户。\n\n### 安装步骤\n\n```bash\n# 1. 克隆仓库\ngit clone https://github.com/weaviate/Verba.git\n\n# 2. 创建并激活虚拟环境\npython3 -m virtualenv venv\nsource venv/bin/activate\n\n# 3. 安装（开发模式）\npip install -e .\n\n# 4. 启动\nverba start\n\n# 5. 访问\n# 访问 http://localhost:8000\n```\n\n资料来源：[README.md:87-105]()\n\n## 方式三：Docker 部署\n\nDocker 部署方式提供完整的容器化环境，包含 Verba 前端和 Weaviate 数据库。\n\n### 架构概览\n\n```mermaid\ngraph LR\n    A[用户浏览器] --> B[Verba Frontend<br/>:8000]\n    B --> C[Verba Backend]\n    C --> D[Weaviate<br/>:8080]\n    E[OLLAMA] --> C\n```\n\n### 快速启动\n\n```bash\n# 克隆仓库\ngit clone https://github.com/weaviate/Verba.git\n\n# 配置环境变量\n# 编辑 goldenverba/.env 文件\n\n# 启动容器\ndocker compose --env-file goldenverba/.env up -d --build\n```\n\n### Docker Compose 配置\n\nVerba 的 `docker-compose.yml` 定义了两个核心服务：\n\n| 服务 | 镜像/构建 | 端口 | 说明 |\n|------|----------|------|------|\n| verba | 本地构建 | 8000:8000 | Verba 应用前端和后端 |\n| weaviate | semitechnologies/weaviate:1.25.10 | 8080:8080 | 向量数据库 |\n\n资料来源：[docker-compose.yml:1-45]()\n\n### Verba 服务配置详情\n\n```yaml\nverba:\n  build:\n    context: ./\n    dockerfile: Dockerfile\n  ports:\n    - 8000:8000\n  environment:\n    - WEAVIATE_URL_VERBA=http://weaviate:8080\n    - OPENAI_API_KEY=$OPENAI_API_KEY\n    - COHERE_API_KEY=$COHERE_API_KEY\n    - OLLAMA_URL=http://host.docker.internal:11434\n    - OLLAMA_MODEL=$OLLAMA_MODEL\n    - OLLAMA_EMBED_MODEL=$OLLAMA_EMBED_MODEL\n  volumes:\n    - ./data:/data/\n  depends_on:\n    weaviate:\n      condition: service_healthy\n  healthcheck:\n    test: wget --no-verbose --tries=3 --spider http://localhost:8000\n    interval: 5s\n    timeout: 10s\n    retries: 5\n```\n\n资料来源：[docker-compose.yml:2-28]()\n\n### 健康检查配置\n\n| 参数 | 值 |\n|------|-----|\n| 测试命令 | wget --no-verbose --tries=3 --spider http://localhost:8000 |\n| 检查间隔 | 5秒 |\n| 超时时间 | 10秒 |\n| 重试次数 | 5次 |\n| 启动延迟 | 10秒 |\n\n资料来源：[docker-compose.yml:29-34]()\n\n### 访问地址\n\n| 服务 | 地址 |\n|------|------|\n| Verba 前端 | http://localhost:8000 |\n| Weaviate | http://localhost:8080 |\n\n## 虚拟环境配置\n\n### 创建虚拟环境\n\n推荐使用虚拟环境避免包冲突：\n\n```bash\n# 使用 virtualenv\npython3 -m virtualenv venv\n\n# 激活虚拟环境\n# Linux/macOS\nsource venv/bin/activate\n# Windows\nvenv\\Scripts\\activate.bat\n```\n\n资料来源：[PYTHON_TUTORIAL.md:1-25]()\n\n### 安装依赖\n\n激活虚拟环境后，使用以下命令安装 Verba：\n\n```bash\npip install goldenverba\n# 或从源码安装\npip install -e .\n```\n\n### 退出虚拟环境\n\n```bash\ndeactivate\n```\n\n## 环境变量配置详解\n\n### 必需的环境变量\n\n根据不同的功能模块，需要配置相应的 API 密钥：\n\n| 功能 | 环境变量 | 来源 |\n|------|---------|------|\n| OpenAI 生成/嵌入 | `OPENAI_API_KEY` | OpenAI 平台 |\n| Cohere 生成/嵌入 | `COHERE_API_KEY` | Cohere 平台 |\n| Ollama 本地模型 | `OLLAMA_URL`, `OLLAMA_MODEL`, `OLLAMA_EMBED_MODEL` | Ollama 部署 |\n| Unstructured 文档处理 | `UNSTRUCTURED_API_KEY`, `UNSTRUCTURED_API_URL` | Unstructured.io |\n| GitHub 数据源 | `GITHUB_TOKEN` | GitHub 设置 |\n\n资料来源：[docker-compose.yml:14-20]()\n\n### 配置优先级\n\n1. 启动时通过命令行参数传入\n2. `.env` 文件中的环境变量\n3. 应用内 UI 配置（首次登录后）\n\n## 部署方式对比\n\n| 特性 | pip 安装 | 源码构建 | Docker |\n|------|---------|---------|--------|\n| 安装难度 | ⭐ 简单 | ⭐⭐ 中等 | ⭐⭐ 中等 |\n| 启动速度 | 快 | 快 | 中等 |\n| 自定义能力 | 有限 | 完整 | 完整 |\n| 包含 Weaviate | 否（需额外配置） | 否（需额外配置） | 是 |\n| 适合场景 | 快速体验 | 开发调试 | 生产部署 |\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|---------|\n| Python 版本不兼容 | 确保使用 Python >= 3.10.0 且 < 3.13.0 |\n| 端口被占用 | 使用 `--port` 参数指定其他端口 |\n| 依赖安装失败 | 创建新的虚拟环境后重试 |\n| Docker 容器无法启动 | 检查 Docker daemon 是否运行，检查端口映射 |\n| Weaviate 连接失败 | 检查 `WEAVIATE_URL_VERBA` 环境变量配置 |\n\n### 验证安装\n\n安装完成后，可以通过以下方式验证：\n\n```bash\n# 检查 Verba 版本\nverba --version\n\n# 访问 Web 界面\n# 打开浏览器访问 http://localhost:8000\n```\n\n## 下一步\n\n部署完成后，建议进行以下操作：\n\n1. **配置 API 密钥**：在 `.env` 文件或应用 UI 中配置所需的 API 密钥\n2. **导入数据**：通过 \"Import Data\" 功能导入文档\n3. **配置 RAG 管道**：在 \"Config\" 页面配置生成模型和检索策略\n4. **开始对话**：在 \"Chat\" 页面开始与数据对话\n\n---\n\n<a id='page-configuration'></a>\n\n## 环境变量与配置\n\n### 相关页面\n\n相关主题：[部署方式](#page-deployment), [后端组件系统](#page-backend-components)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [goldenverba/.env.example](https://github.com/weaviate/Verba/blob/main/goldenverba/.env.example)\n- [frontend/app/types.ts](https://github.com/weaviate/Verba/blob/main/frontend/app/types.ts)\n- [frontend/app/components/Chat/ChatConfig.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatConfig.tsx)\n- [goldenverba/server/types.py](https://github.com/weaviate/Verba/blob/main/goldenverba/server/types.py)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n- [frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n</details>\n\n# 环境变量与配置\n\nVerba（Golden RAGtriever）是一款开源的 RAG（检索增强生成）应用框架，支持多种部署方式和灵活的配置选项。本页面详细介绍 Verba 的环境变量配置、部署类型以及 RAG 管道配置。\n\n## 部署类型概述\n\nVerba 支持四种主要的部署类型，每种类型适用于不同的使用场景：\n\n```mermaid\ngraph TD\n    A[Verba 部署类型] --> B[Local 本地部署]\n    A --> C[Docker 容器部署]\n    A --> D[Weaviate 云服务]\n    A --> E[Custom 自定义部署]\n    \n    B --> B1[本地 Weaviate 实例]\n    C --> C1[Docker Compose 环境]\n    D --> D1[Weaviate Cloud Services]\n    E --> E1[自选 Weaviate 实例]\n```\n\n### 部署类型对比\n\n| 部署类型 | 适用场景 | 配置复杂度 | 资源配置 |\n|---------|---------|-----------|---------|\n| **Local** | 开发测试、个人使用 | 低 | 本地内存 |\n| **Docker** | 本地开发、多服务协作 | 中 | Docker 容器 |\n| **Weaviate** | 云端生产环境 | 低 | WCS 云服务 |\n| **Custom** | 企业自建、有特殊需求 | 高 | 自定义 URL/PORT/API Key |\n\n资料来源：[frontend/app/components/Login/LoginView.tsx:35-85]()\n\n## 环境变量配置\n\nVerba 通过环境变量控制应用的核心行为。以下是支持的环境变量及其功能：\n\n### 核心环境变量\n\n| 环境变量 | 类型 | 默认值 | 说明 |\n|---------|------|--------|------|\n| `DEFAULT_DEPLOYMENT` | string | 无 | 设置默认部署类型，可选值：`Local`、`Docker`、`Weaviate`、`Custom` |\n| `OLLAMA_MODEL` | string | 无 | Ollama 生成模型名称 |\n| `OLLAMA_EMBED_MODEL` | string | 无 | Ollama 嵌入模型名称 |\n\n资料来源：[CHANGELOG.md:12-14]()\n\n### 依赖包版本配置\n\nVerba 的核心依赖版本在 `setup.py` 中定义：\n\n| 依赖包 | 版本要求 | 用途 |\n|-------|---------|------|\n| `weaviate-client` | == 4.9.6 | Weaviate 客户端 |\n| `python-dotenv` | == 1.0.0 | 环境变量加载 |\n| `openpyxl` | == 3.1.5 | Excel 文件处理 |\n| `fastapi` | == 0.111.1 | API 服务框架 |\n| `uvicorn` | == 0.29.0 | ASGI 服务器 |\n| `gunicorn` | == 22.0.0 | WSGI 服务器 |\n| `click` | == 8.1.7 | CLI 工具 |\n| `wasabi` | == 1.1.2 | 日志工具 |\n\n资料来源：[setup.py:18-35]()\n\n## 前端配置系统\n\n### 配置类型定义\n\nVerba 前端使用 TypeScript 定义了完整的配置类型结构：\n\n```typescript\ninterface Credentials {\n  url: string;          // Weaviate 实例 URL\n  deployment: string;   // 部署类型\n  api_key?: string;     // API 密钥（可选）\n}\n```\n\n### 部署模式判断\n\n前端根据 `production` 环境变量决定显示的界面选项：\n\n```mermaid\ngraph TD\n    A[production 值] --> B[\"Demo\"]\n    A --> C[\"Local\"]\n    A --> D[\"Production\"]\n    \n    C --> C1[显示部署选择界面]\n    C1 --> C2[Weaviate 选项]\n    C1 --> C3[Docker 选项]\n    C1 --> C4[Custom 选项]\n    C1 --> C5[Local 选项]\n    \n    B --> B1[显示演示模式入口]\n    D --> D1[直接启动 Verba]\n```\n\n资料来源：[frontend/app/components/Login/LoginView.tsx:45-90]()\n\n### 导航菜单显示逻辑\n\n配置菜单的显示取决于当前部署模式：\n\n| 功能 | Demo 模式 | 其他模式 |\n|-----|----------|---------|\n| Chat 聊天 | ✅ 显示 | ✅ 显示 |\n| Documents 文档 | ✅ 显示 | ✅ 显示 |\n| Import Data 导入数据 | ❌ 隐藏 | ✅ 显示 |\n| Settings 设置 | ❌ 隐藏 | ✅ 显示 |\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:15-40]()\n\n## RAG 配置组件\n\n### ChatConfig 配置面板\n\nChatConfig 组件允许用户配置 RAG 管道的各个组件：\n\n```mermaid\ngraph LR\n    A[聊天配置面板] --> B[Reader 读取器]\n    A --> C[Embedder 嵌入器]\n    A --> D[Generator 生成器]\n    A --> E[Chunker 分块器]\n```\n\n### 配置重置与保存\n\n| 操作 | 函数 | 功能说明 |\n|-----|------|---------|\n| 重置配置 | `onResetConfig` | 恢复默认 RAG 配置 |\n| 保存配置 | `onSaveConfig` | 持久化当前配置 |\n| 获取状态 | `fetchingStatus` | 显示配置加载状态 |\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx]()\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:25-45]()\n\n## 自定义部署配置\n\nCustom 部署类型允许用户指定完整的 Weaviate 连接参数：\n\n### 配置参数\n\n| 参数 | 必填 | 说明 |\n|-----|------|------|\n| Weaviate URL | 是 | Weaviate 实例的完整 URL 地址 |\n| Port | 是 | Weaviate 服务端口 |\n| API Key | 否 | 访问密钥（生产环境建议配置） |\n\n配置界面支持以下输入验证：\n- URL 格式验证\n- 端口范围检查（1-65535）\n- API Key 长度检查\n\n资料来源：[README.md:部署配置章节]()\n\n## 配置数据模型\n\n### 后端类型定义\n\nVerba 后端使用 Python 定义了配置相关的数据结构：\n\n```python\n# RAG 配置模型\nclass RAGConfig:\n    components: Dict[str, Component]\n    \n# 凭证模型  \nclass Credentials:\n    url: str\n    deployment: str\n    api_key: Optional[str]\n```\n\n### 前端类型映射\n\n| 后端类型 | 前端接口 | 用途 |\n|---------|---------|------|\n| `RAGConfig` | `RAGConfig` | RAG 组件配置 |\n| `Credentials` | `credentials` | 连接凭证 |\n| `Deployment` | `production` | 部署环境标识 |\n\n资料来源：[frontend/app/types.ts]()\n资料来源：[goldenverba/server/types.py]()\n\n## 环境配置工作流\n\n### 首次启动配置流程\n\n```mermaid\nsequenceDiagram\n    participant User as 用户\n    participant Frontend as 前端\n    participant Backend as 后端\n    \n    User->>Frontend: 选择部署类型\n    Frontend->>Backend: 发送连接请求\n    Backend->>Weaviate: 验证连接\n    Weaviate-->>Backend: 连接结果\n    Backend-->>Frontend: 返回凭证\n    Frontend->>User: 显示配置界面\n```\n\n### 生产环境配置\n\n对于生产环境部署，建议通过以下方式配置：\n\n1. **设置默认部署**：使用 `DEFAULT_DEPLOYMENT` 环境变量\n2. **配置 API 密钥**：在 Custom 部署模式下启用认证\n3. **配置 CORS**：允许指定的域名访问\n\n## 版本兼容性\n\nVerba 的 Python 版本要求与依赖兼容：\n\n| Python 版本 | 支持状态 | 说明 |\n|------------|---------|------|\n| 3.10 | ✅ 支持 | 最低要求 |\n| 3.11 | ✅ 支持 | 推荐版本 |\n| 3.12 | ✅ 支持 | 当前版本 |\n| 3.13 | ❌ 不支持 | 未测试 |\n\n资料来源：[setup.py:11]()\n\n## 最佳实践\n\n### 开发环境配置\n\n```bash\n# .env 文件示例\nDEFAULT_DEPLOYMENT=Local\nOLLAMA_MODEL=llama2\nOLLAMA_EMBED_MODEL=nomic-embed-text\n```\n\n### 生产环境配置\n\n```bash\n# 生产环境建议\nDEFAULT_DEPLOYMENT=Custom\nWEAVIATE_URL=https://your-instance.weaviate.cloud\nWEAVIATE_API_KEY=your-api-key\n```\n\n### 容器化部署\n\n使用 Docker 部署时，确保环境变量正确传递给容器：\n\n```bash\ndocker run -e DEFAULT_DEPLOYMENT=Docker \\\n           -e WEAVIATE_URL=http://weaviate:8080 \\\n           verba:latest\n```\n\n## 常见问题\n\n**Q: 如何跳过部署选择界面？**\n\nA: 设置 `DEFAULT_DEPLOYMENT` 环境变量为 `Local`、`Docker`、`Weaviate` 或 `Custom` 即可跳过选择步骤。\n\n**Q: Custom 部署需要哪些信息？**\n\nA: 需要提供 Weaviate 实例的 URL、端口和可选的 API 密钥。\n\n**Q: 支持哪些 Weaviate 客户端版本？**\n\nA: Verba 2.1.3 当前使用 `weaviate-client==4.9.6`。\n\n---\n\n*本文档基于 Verba v2.1.3 版本编写*\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 项目说明书",
        "目录",
        "Verba 简介",
        "项目概述",
        "技术架构",
        "部署方式",
        "方式一：pip 安装",
        "方式二：源码构建",
        "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- **Verba 简介**：importance `high`\n  - source_paths: README.md, CHANGELOG.md, TECHNICAL.md\n- **核心功能特性**：importance `high`\n  - source_paths: README.md, goldenverba/components/embedding/__init__.py, goldenverba/components/generation/__init__.py, goldenverba/components/chunking/__init__.py\n- **系统整体架构**：importance `high`\n  - source_paths: TECHNICAL.md, goldenverba/server/api.py, goldenverba/verba_manager.py, goldenverba/components/interfaces.py, frontend/app/page.tsx\n- **前端架构与组件**：importance `high`\n  - source_paths: FRONTEND.md, frontend/app/components/Chat/ChatView.tsx, frontend/app/components/Document/DocumentView.tsx, frontend/app/components/Ingestion/IngestionView.tsx, frontend/app/types.ts\n- **后端组件系统**：importance `high`\n  - source_paths: goldenverba/components/interfaces.py, goldenverba/components/managers.py, goldenverba/components/types.py, goldenverba/components/__init__.py, goldenverba/verba_manager.py\n- **数据导入与处理**：importance `high`\n  - source_paths: goldenverba/components/reader/__init__.py, goldenverba/components/chunking/__init__.py, goldenverba/components/reader/UnstructuredAPI.py, goldenverba/components/chunking/SemanticChunker.py, goldenverba/server/helpers.py\n- **RAG 检索与生成流程**：importance `high`\n  - source_paths: goldenverba/components/retriever/__init__.py, goldenverba/components/retriever/WindowRetriever.py, goldenverba/components/generation/OpenAIGenerator.py, goldenverba/components/generation/OllamaGenerator.py, frontend/app/components/Document/VectorView.tsx\n- **模型集成**：importance `high`\n  - source_paths: goldenverba/components/embedding/OpenAIEmbedder.py, goldenverba/components/embedding/CohereEmbedder.py, goldenverba/components/generation/AnthrophicGenerator.py, goldenverba/components/generation/GroqGenerator.py, goldenverba/components/generation/GeminiGenerator.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-11 17:36:08 UTC\n\n## 目录\n\n- [Verba 简介](#page-introduction)\n- [核心功能特性](#page-features)\n- [系统整体架构](#page-architecture)\n- [前端架构与组件](#page-frontend-structure)\n- [后端组件系统](#page-backend-components)\n- [数据导入与处理](#page-data-ingestion)\n- [RAG 检索与生成流程](#page-rag-pipeline)\n- [模型集成](#page-model-integration)\n- [部署方式](#page-deployment)\n- [环境变量与配置](#page-configuration)\n\n<a id='page-introduction'></a>\n\n## Verba 简介\n\n### 相关页面\n\n相关主题：[核心功能特性](#page-features), [系统整体架构](#page-architecture)\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- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n- [frontend/app/page.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/page.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/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n- [frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n</details>\n\n# Verba 简介\n\nVerba（意为\"词语\"）是由 Weaviate 团队开发的开源 RAG（Retrieval-Augmented Generation，检索增强生成）应用框架，中文名称为\"Golden RAGtriever\"。该项目旨在为用户提供一个简洁友好的界面，快速构建和部署基于私有数据的问答系统。资料来源：[README.md:1]()\n\n## 项目概述\n\nVerba 是一个端到端的 RAG 解决方案，集成了文档导入、语义检索和大语言模型生成功能。用户可以在几步之内完成数据导入和问答配置，无需复杂的代码编写。资料来源：[setup.py:8]()\n\n### 核心特性\n\n| 特性 | 说明 |\n|------|------|\n| 多格式文档支持 | 支持 PDF、文本、CSV、Excel（xlsx/xls）、音频文件等 |\n| 多部署方式 | 支持 pip 安装、源码构建、Docker 部署 |\n| 多 AI 提供商 | OpenAI、Ollama、Novita、Upstage、Groq、Cohere 等 |\n| 可视化界面 | React 构建的现代化 Web 前端 |\n| 灵活配置 | 支持自定义 RAG 管道参数 |\n\n资料来源：[README.md:15-25]()\n\n## 技术架构\n\n### 技术栈\n\nVerba 采用前后端分离的架构设计：\n\n| 层级 | 技术选型 | 说明 |\n|------|----------|------|\n| 前端 | React / Next.js / TypeScript | 构建用户交互界面 |\n| 后端 | Python FastAPI | 提供 RESTful API 服务 |\n| 向量数据库 | Weaviate | 核心向量检索引擎 |\n| 部署环境 | Python 3.10-3.12 | 后端运行环境 |\n\n资料来源：[setup.py:5-6]()\n\n### 系统组件\n\n```mermaid\ngraph TD\n    A[用户界面层] --> B[前端 React 应用]\n    B --> C[FastAPI 后端服务]\n    C --> D[Weaviate 向量数据库]\n    C --> E[文档处理器]\n    C --> F[LLM 生成器]\n    E --> G[多格式 Reader]\n    F --> H[多模型 Generator]\n    G --> I[csv, xlsx, 音频, PDF...]\n    H --> J[OpenAI, Ollama, Novita...]\n```\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:1-50]()\n\n## 部署方式\n\nVerba 支持多种部署模式，满足不同用户的需求：\n\n### 部署模式对比\n\n| 部署方式 | 说明 | 适用场景 |\n|----------|------|----------|\n| Local | 使用本地 Weaviate 实例 | 开发测试 |\n| Docker | Docker Compose 编排部署 | 生产环境快速部署 |\n| Weaviate Cloud (WCS) | 云端托管服务 | 企业级应用 |\n| Custom | 自定义 Weaviate URL 和端口 | 已有 Weaviate 实例 |\n\n资料来源：[frontend/app/components/Login/LoginView.tsx:80-85]()\n\n### 安装方式\n\n```bash\n# 方式一：pip 安装\npip install goldenverba\n\n# 方式二：源码构建\ngit clone https://github.com/weaviate/Verba\npip install -e .\n\n# 方式三：Docker 部署\ngit clone https://github.com/weaviate/Verba\ndocker compose --env-file <your-env-file> up -d --build\n```\n\n资料来源：[README.md:15-35]()\n\n## 功能模块\n\n### 文档管理\n\nVerba 提供完整的文档导入和管理功能：\n\n- **导入方式**：支持单个文件、文件夹批量导入、URL 链接导入\n- **文件格式**：CSV、Excel（xlsx/xls）、PDF、音频文件、文本文件\n- **标签系统**：用户可为文档添加标签进行分类和过滤\n- **来源链接**：可添加原始文档的来源链接，方便溯源\n- **覆盖选项**：支持覆盖同名已存在的文档\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-80]()\n\n### 聊天问答\n\n用户可以通过聊天界面与数据交互：\n\n```mermaid\ngraph LR\n    A[用户提问] --> B[语义检索]\n    B --> C[相关文档块]\n    C --> D[LLM 生成]\n    D --> E[返回答案]\n    C --> F[展示引用来源]\n```\n\n- **语义检索**：基于向量相似度匹配相关文档块\n- **上下文展示**：显示检索到的文档片段及其来源\n- **配置选项**：可调整 RAG 管道的各项参数\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:80-120]()\n\n### 系统设置\n\nSettings 页面提供系统级配置功能：\n\n| 功能 | 说明 |\n|------|------|\n| 重置文档 | 清空所有已导入的文档和块 |\n| 重置配置 | 恢复默认配置参数 |\n| 重置建议 | 清空自动补全建议缓存 |\n| 完全重置 | 删除所有 Verba 相关集合 |\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:30-60]()\n\n## 导航结构\n\n前端应用包含以下主要页面：\n\n| 页面 | 路由标识 | 功能 |\n|------|----------|------|\n| Chat | `CHAT` | 聊天问答主界面 |\n| Documents | `DOCUMENTS` | 文档浏览与管理 |\n| Import Data | `ADD` | 数据导入功能 |\n| Settings | `SETTINGS` | 系统配置 |\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:30-60]()\n\n## 版本历史\n\nVerba 采用语义化版本号，当前版本为 2.1.3。主要版本更新如下：\n\n| 版本 | 特性 |\n|------|------|\n| 2.1.3 | 新增 OLLAMA 环境变量支持、CSV/Excel 文件支持 |\n| 2.1.2 | 新增 Novita 生成器、修复 spaCy 语言问题 |\n| 2.1.1 | 动态获取 OpenAI 模型名称 |\n| 2.1.0 | 新增 Upstage 支持、Groq 支持、AssemblyAI 音频读取 |\n\n资料来源：[CHANGELOG.md:1-30]()\n\n## 环境配置\n\nVerba 支持通过环境变量配置 API 密钥和部署选项：\n\n### 主要环境变量\n\n| 变量名 | 说明 |\n|--------|------|\n| `DEFAULT_DEPLOYMENT` | 默认部署模式（Local/Docker/Weaviate/Custom） |\n| `OLLAMA_MODEL` | Ollama 使用的模型名称 |\n| `OLLAMA_EMBED_MODEL` | Ollama 嵌入模型名称 |\n| `OPENAI_API_KEY` | OpenAI API 密钥 |\n| `WEAVIATE_URL` | Weaviate 实例地址 |\n| `WEAVIATE_API_KEY` | Weaviate API 密钥 |\n\n资料来源：[README.md:40-60]()\n\n## 快速入门\n\n### 步骤一：选择部署方式\n\n首次启动时，用户需要选择连接方式：\n\n1. **Weaviate** - 连接 Weaviate Cloud Service\n2. **Docker** - 使用 Docker 部署的本地实例\n3. **Custom** - 自定义 Weaviate URL 和端口\n4. **Local** - 使用本地完整部署\n\n资料来源：[frontend/app/components/Login/LoginView.tsx:80-120]()\n\n### 步骤二：导入数据\n\n进入\"Import Data\"页面后，用户可以：\n\n- 选择\"Add Files\"添加单个或多个文件\n- 选择\"Add Directory\"批量导入文件夹\n- 选择\"Add URL\"通过链接导入\n\n导入后可在\"Overview\"或\"Configure\"标签页中单独配置每个文件。资料来源：[README.md:65-70]()\n\n### 步骤三：开始问答\n\n数据导入完成后，切换到\"Chat\"页面即可开始提问。系统会根据检索到的相关文档块生成回答，用户可以查看答案的引用来源。资料来源：[README.md:72-75]()\n\n## 项目结构\n\n```\nVerba/\n├── frontend/                    # React 前端应用\n│   └── app/\n│       ├── components/          # React 组件\n│       │   ├── Chat/            # 聊天相关组件\n│       │   ├── Ingestion/       # 数据导入组件\n│       │   ├── Login/           # 登录相关组件\n│       │   ├── Navigation/      # 导航组件\n│       │   └── Settings/        # 设置组件\n│       └── page.tsx             # 主页面\n├── goldenverba/                 # Python 后端包\n│   └── server/                  # 后端服务代码\n├── README.md                    # 项目说明\n├── CHANGELOG.md                 # 变更日志\n├── setup.py                     # 包配置\n└── docker-compose.yml           # Docker 编排文件\n```\n\n## 下一步\n\n- 阅读完整的 [技术文档](./TECHNICAL.md) 了解架构细节\n- 查看 [贡献指南](./CONTRIBUTING.md) 参与项目开发\n- 访问 [GitHub 仓库](https://github.com/weaviate/Verba) 获取最新更新\n\n---\n\n<a id='page-features'></a>\n\n## 核心功能特性\n\n### 相关页面\n\n相关主题：[Verba 简介](#page-introduction), [模型集成](#page-model-integration), [数据导入与处理](#page-data-ingestion)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/weaviate/Verba/blob/main/README.md)\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- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\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/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- [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- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n</details>\n\n# 核心功能特性\n\nVerba（Golden RAGtriever）是一款开源的检索增强生成（RAG）应用框架，旨在为用户提供简化的数据交互和问答体验。该项目基于 Python 3.10-3.12 构建，集成了 Weaviate 向量数据库，支持多种数据源导入、智能分块、语义检索和 LLM 生成功能。资料来源：[setup.py:5](https://github.com/weaviate/Verba/blob/main/setup.py)\n\n## 系统架构概述\n\nVerba 采用前后端分离的微服务架构，前端使用 React/Next.js 构建响应式界面，后端基于 FastAPI 提供 API 服务。系统支持多种部署模式，以适应不同的使用场景。\n\n```mermaid\ngraph TD\n    A[用户界面层] --> B[前端 React 应用]\n    B --> C[WebSocket / REST API]\n    C --> D[FastAPI 后端服务]\n    D --> E[Weaviate 向量数据库]\n    D --> F[LLM 生成器]\n    D --> G[嵌入模型]\n    E --> H[数据存储层]\n    F --> I[外部 LLM API]\n    G --> J[嵌入服务]\n```\n\n## 部署模式\n\nVerba 提供四种部署模式，满足从本地开发到云端生产环境的不同需求。\n\n| 部署模式 | 描述 | 适用场景 |\n|---------|------|---------|\n| Local | 使用 Weaviate Embedded 本地嵌入式实例 | 开发测试 |\n| Docker | 通过 Docker Compose 启动完整容器化环境 | 本地部署 |\n| Weaviate Cloud (WCS) | 连接 Weaviate 云服务 | 云端生产环境 |\n| Custom | 自定义 Weaviate 实例 URL、端口和 API 密钥 | 企业内部部署 |\n\n资料来源：[README.md:40-44](https://github.com/weaviate/Verba/blob/main/README.md)\n\n### 部署模式选择界面\n\n在 `LoginView.tsx` 组件中实现了部署模式选择逻辑，用户可以通过界面选择所需的部署方式。\n\n```typescript\n// frontend/app/components/Login/LoginView.tsx\n{production == \"Local\" && (\n  <VerbaButton\n    title=\"Weaviate\"\n    Icon={FaDatabase}\n    onClick={() => setSelectedDeployment(\"Weaviate\")}\n  />\n)}\n```\n\n## 文档导入与处理\n\nVerba 提供灵活的文档导入功能，支持多种数据格式和来源。\n\n### 支持的文件格式\n\n在 2.1.3 版本中，DefaultReader 扩展了以下文件格式支持：\n\n| 文件类型 | 扩展名 | 描述 |\n|---------|-------|------|\n| CSV 表格 | `.csv` | 逗号分隔值文件 |\n| Excel 工作簿 | `.xlsx`, `.xls` | Microsoft Excel 文件 |\n| 纯文本 | `.txt` | 纯文本文件 |\n| Markdown | `.md` | Markdown 格式文档 |\n| HTML | `.html`, `.htm` | 网页内容 |\n\n资料来源：[CHANGELOG.md:8-10](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n### 文档导入流程\n\n```mermaid\ngraph LR\n    A[选择数据源] --> B[添加文件/目录/URL]\n    B --> C{数据源类型}\n    C -->|文件| D[文件读取器]\n    C -->|目录| E[批量文件处理]\n    C -->|URL| F[网页抓取器]\n    D --> G[文档解析]\n    E --> G\n    F --> G\n    G --> H[文档对象创建]\n    H --> I[配置处理管道]\n    I --> J[存储至 Weaviate]\n```\n\n### 导入配置功能\n\n`BasicSettingView.tsx` 组件提供了文档导入时的基本配置选项：\n\n- **来源链接（Source Link）**：添加文档原始来源的引用链接，用户可通过文档浏览器中的\"查看来源\"按钮访问\n- **标签（Labels）**：为文档添加自定义标签，便于分类和检索\n\n```typescript\n// frontend/app/components/Ingestion/BasicSettingView.tsx\n<div className=\"flex gap-2 justify-between items-center text-text-verba\">\n  <p className=\"flex min-w-[8vw]\">Source Link</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={source}\n      onChange={handleSourceChange}\n      disabled={blocked}\n    />\n  </label>\n</div>\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.tsx)\n\n## 文档对象模型\n\nVerba 使用统一的 `Document` 类表示所有文档内容，该类封装了文档的元数据和内容信息。\n\n### Document 类结构\n\n```python\n# goldenverba/components/document.py\n@dataclass\nclass Document:\n    title: str              # 文档标题\n    content: str            # 文档正文内容\n    extension: str          # 文件扩展名\n    doc_id: str = \"\"        # 文档唯一标识\n    content_id: str = \"\"   # 内容块唯一标识\n    labels: List[str] = field(default_factory=list)  # 标签列表\n    source: str = \"\"        # 来源链接\n    fileSize: int = 0      # 文件大小\n    metadata: str = \"\"     # 元数据字符串\n    meta: dict = field(default_factory=dict)  # 元数据字典\n```\n\n资料来源：[goldenverba/components/document.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/document.py)\n\n### 创建文档工厂函数\n\n```python\ndef create_document(content: str, fileConfig: FileConfig) -> Document:\n    \"\"\"从文件内容创建 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## RAG 处理管道\n\nVerba 实现了完整的 RAG（检索增强生成）处理管道，包括读取器、分块器、嵌入器和生成器四个核心组件。\n\n### 组件架构\n\n```mermaid\ngraph TD\n    subgraph RAG管道\n        A[Reader 读取器] --> B[Chunking 分块器]\n        B --> C[Embedding 嵌入器]\n        C --> D[Vector Store 向量存储]\n        D --> E[Retrieval 检索]\n        E --> F[Generator 生成器]\n        F --> G[Response 响应]\n    end\n```\n\n### HTML 读取器实现\n\n`HTMLReader.py` 提供了网页内容抓取和转换功能，支持以下配置选项：\n\n| 配置项 | 类型 | 默认值 | 描述 |\n|-------|------|-------|------|\n| URLs | string[] | [] | 要抓取的 URL 列表 |\n| Convert To Markdown | bool | false | 是否转换为 Markdown 格式 |\n| Recursive | bool | false | 是否递归抓取链接页面 |\n| Max Depth | number | 3 | 递归抓取的最大深度 |\n\n```python\n# goldenverba/components/reader/HTMLReader.py\nasync def load(self, config: dict, fileConfig: FileConfig) -> list[Document]:\n    reader = BasicReader()\n    urls = config[\"URLs\"].values\n    to_markdown = config[\"Convert To Markdown\"].value\n    recursive = config[\"Recursive\"].value\n    max_depth = int(config[\"Max Depth\"].value)\n    \n    documents = []\n    processed_urls = set()\n    \n    async with aiohttp.ClientSession() as session:\n        for url in urls:\n            await self.process_url(...)\n```\n\n资料来源：[goldenverba/components/reader/HTMLReader.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/reader/HTMLReader.py)\n\n## 聊天问答界面\n\nVerba 的聊天界面允许用户使用自然语言查询已导入的文档，系统会返回语义相关的文档片段并生成答案。\n\n### 聊天流程\n\n```mermaid\nsequenceDiagram\n    participant U as 用户\n    participant C as 前端界面\n    participant S as 后端服务\n    participant W as Weaviate\n    participant L as LLM\n    \n    U->>C: 输入问题\n    C->>S: 发送查询请求\n    S->>W: 语义检索相关片段\n    W-->>S: 返回 Top-K 相关片段\n    S->>L: 发送上下文+问题\n    L-->>S: 生成回答\n    S-->>C: 返回答案+引用片段\n    C->>U: 显示结果\n```\n\n### 界面组件结构\n\n`ChatInterface.tsx` 实现了完整的聊天交互界面，包含以下功能区域：\n\n- **消息显示区**：展示用户问题和系统回答\n- **配置面板**：调整 RAG 管道参数\n- **输入区域**：文本输入框用于提交问题\n- **状态指示器**：显示检索（Retrieving）和生成（Generating）状态\n\n```typescript\n// frontend/app/components/Chat/ChatInterface.tsx\n<span className=\"text-text-alt-verba loading loading-dots loading-md\"></span>\n<p className=\"text-text-alt-verba\">\n  {fetchingStatus === \"CHUNKS\" && \"Retrieving...\"}\n  {fetchingStatus === \"RESPONSE\" && \"Generating...\"}\n</p>\n```\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n\n### 取消操作\n\n用户可以随时取消正在进行的检索或生成操作：\n\n```typescript\n<button\n  onClick={() => {\n    setFetchingStatus(\"DONE\");\n    isFetching.current = false;\n  }}\n  className=\"btn btn-circle btn-sm bg-bg-alt-verba hover:bg-warning-verba\"\n>\n  <MdCancel size={15} />\n</button>\n```\n\n## 生成器与嵌入器\n\nVerba 支持多种 LLM 提供商和嵌入模型，用户可根据需求灵活配置。\n\n### 支持的 LLM 提供商\n\n| 提供商 | 类型 | 配置方式 |\n|-------|------|---------|\n| OpenAI | 云端 API | API Key + URL |\n| Anthropic | 云端 API | API Key |\n| Cohere | 云端 API | API Key |\n| Ollama | 本地/自托管 | 本地服务 URL + 模型名称 |\n| Upstage | 云端 API | API Key |\n| Novita | 云端 API | API Key |\n| Groq | 云端 API | API Key |\n\n资料来源：[CHANGELOG.md:4-24](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n### 环境变量配置\n\nVerba 支持通过环境变量配置模型：\n\n| 环境变量 | 描述 |\n|---------|------|\n| `OLLAMA_MODEL` | Ollama 默认模型 |\n| `OLLAMA_EMBED_MODEL` | Ollama 嵌入模型 |\n| `DEFAULT_DEPLOYMENT` | 默认部署模式 |\n\n## 系统设置与管理\n\n### InfoView 设置面板\n\n`InfoView.tsx` 组件提供了全面的系统管理功能：\n\n```mermaid\ngraph TD\n    A[设置面板] --> B[集群信息]\n    A --> C[集合管理]\n    A --> D[重置操作]\n    \n    B --> B1[节点状态]\n    B --> B2[分片信息]\n    \n    C --> C1[集合列表]\n    C --> C2[对象计数]\n    \n    D --> D1[重置文档]\n    D --> D2[重置配置]\n    D --> D3[重置建议]\n    D --> D4[重置全部]\n```\n\n### 重置操作\n\n| 操作 | 描述 | 影响范围 |\n|-----|------|---------|\n| Reset Documents | 清除所有文档和分块 | 集合中的文档数据 |\n| Reset Config | 重置配置参数 | RAG 管道配置 |\n| Reset Suggestions | 重置自动完成建议 | 搜索建议缓存 |\n| Reset Verba | 完整重置 | 删除所有 Verba 相关集合 |\n\n```typescript\n// frontend/app/components/Settings/InfoView.tsx\n<UserModalComponent\n  modal_id=\"reset-documents\"\n  title=\"Reset Documents\"\n  text=\"Are you sure you want to reset all documents? This will clear all documents and chunks from Verba.\"\n  triggerAccept={resetDocuments}\n  triggerString=\"Reset\"\n/>\n```\n\n## 导航与界面布局\n\n### 顶部导航栏\n\n`NavbarComponent.tsx` 实现了应用的主要导航结构：\n\n```mermaid\ngraph LR\n    A[导航栏] --> B[Chat 聊天]\n    A --> C[Documents 文档]\n    A --> D[Import Data 导入数据]\n    A --> E[Settings 设置]\n    \n    style A fill:#e1f5fe\n    style B fill:#b3e5fc\n    style C fill:#b3e5fc\n    style D fill:#b3e5fc\n    style E fill:#b3e5fc\n```\n\n### 导航按钮组件\n\n```typescript\n// frontend/app/components/Navigation/NavbarComponent.tsx\n<NavbarButton\n  hide={false}\n  Icon={IoChatbubbleSharp}\n  title=\"Chat\"\n  currentPage={currentPage}\n  setCurrentPage={setCurrentPage}\n  setPage=\"CHAT\"\n/>\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\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n\n## 文档浏览器\n\n### ContentView 文档内容展示\n\n`ContentView.tsx` 组件提供了文档内容的分页浏览功能：\n\n- **分块导航**：支持按块（Chunk）或按页（Page）浏览\n- **内容渲染**：将文档内容片段渲染为可读文本\n- **标签显示**：展示文档关联的标签\n\n```typescript\n// frontend/app/components/Document/ContentView.tsx\n<div className=\"flex justify-center items-center gap-2 p-3 bg-bg-alt-verba\">\n  <VerbaButton\n    title={\"Previous \" + (chunkScores ? \"Chunk\" : \"Page\")}\n    onClick={previousPage}\n    className=\"btn-sm min-w-min max-w-[200px]\"\n  />\n  <div className=\"flex items-center\">\n    <p className=\"text-xs text-text-verba\">\n      {chunkScores ? \"Chunk \" : \"Page \"} {page}\n    </p>\n  </div>\n  <VerbaButton\n    title={\"Next \" + (chunkScores ? \"Chunk\" : \"Page\")}\n    onClick={nextPage}\n  />\n</div>\n```\n\n## 快速入门\n\n### 安装方式\n\nVerba 提供三种安装方式：\n\n| 安装方式 | 命令 | 适用场景 |\n|---------|------|---------|\n| pip 安装 | `pip install goldenverba` | 快速体验 |\n| 源码构建 | `git clone && pip install -e .` | 开发调试 |\n| Docker 部署 | `docker compose --env-file <env-file> up -d --build` | 生产环境 |\n\n```bash\n# pip 安装\npip install goldenverba\n\n# 源码构建\ngit clone https://github.com/weaviate/Verba\npip install -e .\n\n# Docker 部署\ngit clone https://github.com/weaviate/Verba\ndocker compose --env-file <your-env-file> up -d --build\n```\n\n### 环境变量配置\n\n在项目根目录创建 `.env` 文件配置 API 密钥和环境变量。Verba 会自动读取该文件中的配置。\n\n> 注意：仅设置需要使用的环境变量，缺失或错误的值可能导致运行错误。\n\n资料来源：[README.md:58-75](https://github.com/weaviate/Verba/blob/main/README.md)\n\n## 版本历史\n\n| 版本 | 发布内容 |\n|-----|---------|\n| 2.1.3 | 新增 CSV/Excel 支持，添加 Ollama 环境变量 |\n| 2.1.2 | 添加 Novita 生成器，修复 spaCy 语言问题 |\n| 2.1.1 | OpenAI 模型名称动态获取 |\n| 2.1.0 | 添加 Upstage 组件，新增 Custom 部署模式 |\n\n资料来源：[CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n---\n\n<a id='page-architecture'></a>\n\n## 系统整体架构\n\n### 相关页面\n\n相关主题：[Verba 简介](#page-introduction), [前端架构与组件](#page-frontend-structure), [后端组件系统](#page-backend-components)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [TECHNICAL.md](https://github.com/weaviate/Verba/blob/main/TECHNICAL.md)\n- [goldenverba/server/api.py](https://github.com/weaviate/Verba/blob/main/goldenverba/server/api.py)\n- [goldenverba/verba_manager.py](https://github.com/weaviate/Verba/blob/main/goldenverba/verba_manager.py)\n- [goldenverba/components/interfaces.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/interfaces.py)\n- [frontend/app/page.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/page.tsx)\n</details>\n\n# 系统整体架构\n\n## 概述\n\nVerba（Golden RAGtriever）是一个开源的检索增强生成（RAG）应用程序，旨在为用户提供一个简化、易用的 RAG 解决方案。该项目由 Weaviate 团队开发维护，支持多种部署方式和 LLM 提供商集成。资料来源：[README.md](https://github.com/weaviate/Verba/blob/main/README.md)\n\n## 技术栈概览\n\nVerba 采用前后端分离的架构设计，主要由以下技术组件构成：\n\n| 层次 | 技术选型 | 说明 |\n|------|----------|------|\n| 前端框架 | Next.js (React) | 用户界面与交互逻辑 |\n| 后端框架 | FastAPI + Uvicorn | RESTful API 服务 |\n| 数据存储 | Weaviate | 向量数据库与全文检索 |\n| 包管理 | setuptools | Python 包发布配置 |\n| 运行时 | Python 3.10-3.12 | 后端运行环境 |\n\n资料来源：[setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n\n## 系统架构图\n\n```mermaid\ngraph TD\n    subgraph 前端层[\"前端层 (Next.js)\"]\n        A[用户界面] --> B[页面路由]\n        B --> C[组件库]\n        C --> D[状态管理]\n    end\n    \n    subgraph 后端层[\"后端层 (FastAPI)\"]\n        E[API 路由] --> F[Verba Manager]\n        F --> G[组件系统]\n        G --> H[Weaviate 客户端]\n    end\n    \n    subgraph 数据层[\"数据层 (Weaviate)\"]\n        I[向量存储] --> J[集合与对象]\n    end\n    \n    K[文档导入] --> E\n    L[聊天查询] --> E\n    E --> H\n    H --> I\n    \n    M[LLM 提供商] --> G\n    N[嵌入模型] --> G\n```\n\n## 核心组件架构\n\n### 前端组件结构\n\n前端采用 Next.js 框架构建，主要包含以下核心组件模块：\n\n| 组件模块 | 文件路径 | 功能描述 |\n|----------|----------|----------|\n| 导航组件 | `frontend/app/components/Navigation/` | 页面导航与菜单 |\n| 聊天组件 | `frontend/app/components/Chat/` | 对话界面与消息展示 |\n| 设置组件 | `frontend/app/components/Settings/` | 配置管理界面 |\n| 登录组件 | `frontend/app/components/Login/` | 部署选择与初始配置 |\n| 导入组件 | `frontend/app/components/Ingestion/` | 数据导入功能 |\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n\n### 后端核心模块\n\n#### Verba Manager\n\nVerba Manager 是系统的核心管理单元，负责协调各个组件之间的交互。该模块处理文档管理、RAG 配置、用户凭证等核心业务逻辑。\n\n```python\n# 核心管理功能\n- 文档生命周期管理\n- RAG 管道配置\n- 凭证验证与存储\n- 部署环境适配\n```\n\n资料来源：[goldenverba/verba_manager.py](https://github.com/weaviate/Verba/blob/main/goldenverba/verba_manager.py)\n\n#### 组件接口系统\n\nVerba 采用基于接口的组件化设计，所有核心功能都通过标准化接口实现：\n\n```mermaid\ngraph LR\n    A[Reader 接口] --> B[文档读取]\n    C[Embedder 接口] --> D[向量嵌入]\n    E[Generator 接口] --> F[文本生成]\n    G[Chunker 接口] --> H[文档分块]\n```\n\n资料来源：[goldenverba/components/interfaces.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/interfaces.py)\n\n### 文档对象模型\n\n```mermaid\nclassDiagram\n    class Document {\n        +str title\n        +str content\n        +str extension\n        +str fileSize\n        +list labels\n        +str source\n        +dict meta\n        +str metadata\n    }\n    \n    class FileConfig {\n        +str filename\n        +str extension\n        +str content\n        +str source\n        +list labels\n        +str file_size\n        +dict metadata\n    }\n    \n    Document --> FileConfig : create from\n```\n\n资料来源：[goldenverba/components/document.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/document.py)\n\n## 部署架构\n\nVerba 支持多种部署模式，以适应不同的使用场景：\n\n```mermaid\ngraph TD\n    A[启动 Verba] --> B{部署模式选择}\n    \n    B --> C[Local 模式]\n    B --> D[Docker 模式]\n    B --> E[Weaviate 云服务]\n    B --> F[Custom 自定义]\n    \n    C --> G[本地 Ollama]\n    C --> H[本地 HuggingFace]\n    \n    D --> I[Docker Compose]\n    \n    E --> J[WCS 云端]\n    \n    F --> K[自定义 Weaviate 实例]\n    K --> L[自定义 API 端点]\n```\n\n资料来源：[frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n\n### 部署模式对比\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| Local | 本地 Ollama/HuggingFace | 开发测试 |\n| Docker | Docker Compose 部署 | 快速体验 |\n| Weaviate | Weaviate Cloud Services | 生产环境 |\n| Custom | 自定义 Weaviate 实例 | 已有基础设施 |\n\n## RAG 处理流程\n\n```mermaid\ngraph LR\n    A[数据导入] --> B[文档读取 Reader]\n    B --> C[分块处理 Chunker]\n    C --> D[向量化 Embedder]\n    D --> E[Weaviate 存储]\n    \n    F[用户查询] --> G[向量化查询]\n    G --> H[向量检索]\n    H --> I[上下文组装]\n    I --> J[LLM 生成]\n    J --> K[返回结果]\n```\n\n### 聊天界面交互\n\n聊天模块负责用户与 RAG 系统之间的交互：\n\n```mermaid\nstateDiagram-v2\n    [*] --> 空闲状态: 页面加载\n    空闲状态 --> 检索中: 用户发送消息\n    检索中 --> 生成中: 获取到上下文\n    生成中 --> 空闲状态: 生成完成\n    检索中 --> 空闲状态: 取消操作\n    生成中 --> 空闲状态: 取消操作\n```\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.tsx)\n\n## 前端页面结构\n\n```mermaid\ngraph TD\n    A[主页面] --> B[导航栏]\n    A --> C[内容区域]\n    A --> D[页脚]\n    \n    B --> B1[Chat 聊天]\n    B --> B2[Documents 文档]\n    B --> B3[Import Data 导入]\n    B --> B4[Settings 设置]\n    \n    C --> C1{生产模式判断}\n    C1 -->|非 Demo| B3\n    C1 -->|Demo| 隐藏导入\n```\n\n资料来源：[frontend/app/page.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/page.tsx)\n\n## API 服务架构\n\nFastAPI 后端提供以下核心服务接口：\n\n| 接口类别 | 功能 | 通信方式 |\n|----------|------|----------|\n| 文档管理 | 上传、查询、删除文档 | REST API |\n| RAG 配置 | 模型选择、参数调整 | REST API |\n| 聊天接口 | 查询处理与响应生成 | WebSocket + REST |\n| 系统状态 | 健康检查、配置获取 | REST API |\n\n资料来源：[goldenverba/server/api.py](https://github.com/weaviate/Verba/blob/main/goldenverba/server/api.py)\n\n## 初始化流程\n\n```mermaid\nsequenceDiagram\n    participant U as 用户\n    participant F as 前端\n    participant B as 后端 API\n    participant W as Weaviate\n    \n    U->>F: 访问应用\n    F->>B: 健康检查\n    B->>W: 连接验证\n    W-->>B: 连接状态\n    B-->>F: 部署配置\n    F->>U: 显示登录界面\n    \n    U->>F: 选择部署模式\n    F->>B: 验证凭证\n    B->>W: 初始化集合\n    W-->>B: 初始化完成\n    B-->>F: 登录成功\n    F->>U: 进入主界面\n```\n\n## 环境配置\n\n系统通过环境变量进行配置管理：\n\n| 变量名 | 说明 | 示例值 |\n|--------|------|--------|\n| `DEFAULT_DEPLOYMENT` | 默认部署模式 | Local/Docker/Weaviate/Custom |\n| `OLLAMA_MODEL` | Ollama 模型名称 | llama2 |\n| `OLLAMA_EMBED_MODEL` | Ollama 嵌入模型 | nomic-embed-text |\n| `WEAVIATE_URL` | Weaviate 连接地址 | https://xxx.weaviate.cloud |\n| `WEAVIATE_API_KEY` | Weaviate API 密钥 | 保密 |\n\n资料来源：[CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n\n## 依赖关系\n\n```mermaid\ngraph TD\n    A[goldenverba] --> B[weaviate-client]\n    A --> C[fastapi]\n    A --> D[uvicorn]\n    A --> E[click]\n    \n    F[前端] --> G[Next.js]\n    F --> H[React]\n    F --> I[daisyUI]\n```\n\n核心依赖版本：\n\n- Python: 3.10.0 - 3.12.0\n- weaviate-client: 4.9.6\n- fastapi: 0.111.1\n- uvicorn: 0.29.0\n\n资料来源：[setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n\n## 总结\n\nVerba 采用现代化的前后端分离架构，通过组件化设计实现了高度的灵活性和可扩展性。系统支持多种部署模式，能够适应从本地开发到云端生产的各种使用场景。RAG 管道的模块化设计使得用户可以方便地切换不同的 LLM 提供商和嵌入模型，同时保持核心功能的稳定性和一致性。\n\n---\n\n<a id='page-frontend-structure'></a>\n\n## 前端架构与组件\n\n### 相关页面\n\n相关主题：[系统整体架构](#page-architecture), [后端组件系统](#page-backend-components), [RAG 检索与生成流程](#page-rag-pipeline)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\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/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/Chat/ChatInterface.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatInterface.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/Document/ContentView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Document/ContentView.tsx)\n- [frontend/app/components/Ingestion/FileSelectionView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/FileSelectionView.tsx)\n- [frontend/app/page.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/page.tsx)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n</details>\n\n# 前端架构与组件\n\n## 概述\n\nVerba 前端是基于 Next.js 构建的 React 应用，采用组件化架构设计。该应用作为 RAG（检索增强生成）系统的用户界面，提供聊天交互、文档管理、数据导入和系统设置等功能。前端使用 TypeScript 开发，通过 WebSocket 与后端服务通信，并使用 Tailwind CSS 和 daisyUI 进行样式管理。资料来源：[setup.py:1-12]()\n\n## 技术栈\n\n| 技术类别 | 技术选型 | 用途 |\n|---------|---------|------|\n| 框架 | Next.js | 应用框架与路由管理 |\n| 语言 | TypeScript | 类型安全的开发 |\n| UI 库 | React + daisyUI | 组件与样式系统 |\n| 样式 | Tailwind CSS | 原子化 CSS 样式 |\n| 状态管理 | React Context + useRef | 组件状态与全局状态 |\n| 实时通信 | Socket.IO | WebSocket 双向通信 |\n| 渲染 | ReactMarkdown + SyntaxHighlighter | Markdown 与代码高亮 |\n\n## 组件架构\n\n### 组件目录结构\n\nVerba 前端组件采用功能模块化组织，所有组件位于 `frontend/app/components/` 目录下，按功能分为以下子目录：\n\n```\nfrontend/app/components/\n├── Chat/           # 聊天相关组件\n├── Document/       # 文档浏览组件\n├── Ingestion/      # 数据导入组件\n├── Login/          # 登录与初始化组件\n├── Navigation/     # 导航组件\n└── Settings/       # 设置组件\n```\n\n资料来源：[frontend/app/components/Chat/ChatMessage.tsx](), [frontend/app/components/Navigation/NavbarComponent.tsx]()\n\n### 核心组件关系\n\n```mermaid\ngraph TD\n    A[主页面 page.tsx] --> B[NavbarComponent 导航栏]\n    A --> C[主内容区域]\n    \n    C --> D{currentPage 状态}\n    D -->|CHAT| E[ChatInterface 聊天界面]\n    D -->|DOCUMENTS| F[DocumentView 文档视图]\n    D -->|ADD| G[IngestionView 导入视图]\n    D -->|SETTINGS| H[InfoView 设置视图]\n    D -->|LOGIN| I[LoginView 登录视图]\n    \n    E --> J[ChatMessage 消息组件]\n    E --> K[ChatConfig 聊天配置]\n    \n    G --> L[FileSelectionView 文件选择]\n    G --> M[BasicSettingView 基础设置]\n    \n    B --> N[StatusMessenger 状态消息]\n```\n\n## 导航系统\n\n### 导航栏组件\n\nNavbarComponent 是应用的主导航组件，负责页面路由切换和状态显示。该组件根据 `production` 环境变量决定是否显示特定功能按钮。\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:1-150]()\n\n**导航按钮配置表：**\n\n| 按钮标题 | 图标 | 页面路由 | 显示条件 |\n|---------|------|---------|---------|\n| Chat | IoChatbubbleSharp | CHAT | 始终显示 |\n| Import Data | IoMdAddCircle | ADD | production !== \"Demo\" |\n| Documents | IoDocumentSharp | DOCUMENTS | 始终显示 |\n| Settings | IoSettingsSharp | SETTINGS | production !== \"Demo\" |\n\n导航栏支持响应式设计，在移动端（md 断点以下）以汉堡菜单形式展示，在桌面端以横向按钮组形式展示。组件使用 `useState` 管理当前页面状态，通过 `setCurrentPage` 回调向上层组件传递页面变更。资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:50-100]()\n\n### 状态消息组件\n\nStatusMessengerComponent 提供全局状态通知功能，通过 `AnimatePresence` 实现动画效果。消息根据类型（info、success、error）显示不同颜色，消息有效期为 5 秒。资料来源：[frontend/app/components/Navigation/StatusMessenger.tsx:1-40]()\n\n```mermaid\nsequenceDiagram\n    participant Parent as 父组件\n    participant StatusMessenger\n    participant Message as 消息队列\n    \n    Parent->>StatusMessenger: addStatusMessage(type, message)\n    StatusMessenger->>Message: 添加消息到队列\n    Note over Message: 设置 timestamp\n    StatusMessenger->>StatusMessenger: 过滤 5 秒内的消息\n    StatusMessenger->>StatusMessenger: 动画显示消息\n    Note over StatusMessenger: 5 秒后自动移除\n```\n\n## 聊天模块\n\n### 聊天界面组件\n\nChatInterface 是聊天功能的核心组件，管理消息列表、输入框和状态显示。组件支持以下消息类型：\n\n- `user`：用户发送的消息，右对齐显示\n- `system`：系统响应，左对齐显示，支持 Markdown 渲染\n- `error`：错误提示，使用警告色背景\n- `retrieval`：检索状态信息\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:1-200]()\n\n**消息状态与样式映射表：**\n\n| 消息类型 | 背景色类名 | 排列方式 | 特殊处理 |\n|---------|-----------|---------|---------|\n| user | bg-primary-verba | 右对齐 | 无 |\n| system | bg-bg-alt-verba | 左对齐 | Markdown 渲染 |\n| error | bg-warning-verba | 左对齐 | 无 |\n| retrieval | bg-bg-verba | 左对齐 | 无 |\n\n聊天界面包含实时检索状态指示器，显示 \"Retrieving...\" 或 \"Generating...\" 状态，用户可通过取消按钮终止请求。组件使用 `useRef` 管理 `isFetching` 状态以避免闭包问题。资料来源：[frontend/app/components/Chat/ChatInterface.tsx:80-120]()\n\n### 聊天消息组件\n\nChatMessage 负责渲染单条聊天消息，支持富文本内容展示。对于 system 类型消息，组件使用 ReactMarkdown 和 SyntaxHighlighter 进行 Markdown 解析和代码语法高亮。资料来源：[frontend/app/components/Chat/ChatMessage.tsx:1-100]()\n\n代码高亮支持根据主题（dark/light）切换样式：\n- **暗色主题**：使用 oneDark 配色\n- **亮色主题**：使用 oneLight 配色\n\n组件还支持 `cached` 属性，当消息为缓存内容时显示数据库图标。资料来源：[frontend/app/components/Chat/ChatMessage.tsx:30-60]()\n\n## 文档管理模块\n\n### 文档内容视图\n\nContentView 组件提供文档和 Chunk 的分页浏览功能。组件支持两种内容模式：\n\n1. **Chunk 模式**：显示检索到的文档片段，配合相关性分数\n2. **Page 模式**：显示原始文档分页\n\n资料来源：[frontend/app/components/Document/ContentView.tsx:1-150]()\n\n**内容显示特征表：**\n\n| 特征 | 显示条件 | 样式 |\n|-----|---------|------|\n| Chunk ID | chunkScores 存在 | 圆角标签 bg-bg-alt-verba |\n| 相关性标识 | score > 0 | 圆角标签 bg-primary-verba + 星星图标 |\n| 代码块 | 内容包含代码 | SyntaxHighlighter 高亮 |\n\n组件使用 Previous/Next 按钮进行分页导航，分页逻辑根据当前模式（Chunk 或 Page）显示不同的按钮文本。资料来源：[frontend/app/components/Document/ContentView.tsx:100-130]()\n\n## 数据导入模块\n\n### 文件选择视图\n\nFileSelectionView 组件管理导入文件的列表展示和选择状态。组件支持多种 Reader 类型筛选，包括 URL 类型 Reader 的下拉菜单选择。资料来源：[frontend/app/components/Ingestion/FileSelectionView.tsx:1-100]()\n\n**文件组件交互流程：**\n\n```mermaid\ngraph LR\n    A[FileSelectionView] --> B[FileComponent 列表]\n    B --> C{用户操作}\n    C -->|选择| D[setSelectedFileData]\n    C -->|删除| E[handleDeleteFile]\n    C -->|添加URL| F[handleAddURL]\n    \n    G[导入就绪] --> H[Import Selected 按钮]\n    H --> I[触发导入流程]\n```\n\n文件列表区域使用 `overflow-auto` 支持滚动，导入操作仅在 WebSocket 在线时可用。资料来源：[frontend/app/components/Ingestion/FileSelectionView.tsx:80-120]()\n\n### 基础设置视图\n\nBasicSettingView 组件提供导入文件的详细配置选项，包括 RAG Pipeline 各组件的配置。资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-150]()\n\n**配置项表：**\n\n| 配置项 | 输入类型 | 说明 |\n|-------|---------|------|\n| Source Link | 文本输入 | 文档原始来源链接 |\n| Labels | 标签输入 + 添加按钮 | 文档分类标签 |\n| Chunker | 只读文本 | 分块策略配置 |\n| Embedder | 只读文本 | 嵌入模型配置 |\n| Metadata | Textarea | 键值对元数据 |\n| Overwrite | Checkbox | 是否覆盖同名文档 |\n\n组件使用 `onKeyDown` 事件监听 Enter 键快速添加标签，文本域最大高度限制为 150px。资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:50-100]()\n\n## 设置模块\n\n### 信息视图\n\nInfoView 组件显示系统状态信息和提供重置功能入口。组件从后端 API 获取集群节点信息和 Collection 列表。资料来源：[frontend/app/components/Settings/InfoView.tsx:1-100]()\n\n**信息展示区域表：**\n\n| 区域 | 内容 | 加载状态 |\n|-----|------|---------|\n| Nodes | 节点名称、状态、分片数 | loading-dots |\n| Collections | 集合名称、对象数量 | loading-dots |\n\nInfoView 提供四种重置操作，分别通过 UserModalComponent 组件确认后执行：\n\n1. **Reset Documents**：清除所有文档和分块\n2. **Reset Config**：重置配置\n3. **Reset Verba**：删除 Verba 相关 Collection\n4. **Reset Suggestions**：清除自动完成建议\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:90-120]()\n\n## 登录与初始化\n\n### 登录视图\n\nLoginView 组件处理应用初始化和部署类型选择。根据 `production` 环境变量显示不同界面：资料来源：[frontend/app/components/Login/LoginView.tsx:1-80]()\n\n**部署类型选择表：**\n\n| 部署类型 | 图标 | 说明 |\n|---------|------|------|\n| Weaviate | FaDatabase | 连接 Weaviate 服务 |\n| Docker | FaDocker | Docker 部署模式 |\n| Custom | TbDatabaseEdit | 自定义部署 |\n| Local | FaLaptopCode | 本地开发模式 |\n\n组件使用 `isConnecting` 状态管理连接中动画，通过 `setSelectedDeployment` 回调传递选择结果。资料来源：[frontend/app/components/Login/LoginView.tsx:50-70]()\n\n### 入门引导\n\nGettingStartedComponent 组件在首次使用时显示引导界面，包含项目介绍和缩略图展示。用户点击 \"Let's get started\" 按钮后通过 localStorage 记录已显示状态。资料来源：[frontend/app/components/Login/GettingStarted.tsx:1-60]()\n\n## 主页面结构\n\npage.tsx 作为应用的根组件，组合所有子组件并管理全局状态。主要功能包括：资料来源：[frontend/app/page.tsx:1-100]()\n\n1. **生产环境检测**：根据 `NEXT_PUBLIC_VERBA_PRODUCTION` 环境变量决定显示模式\n2. **组件挂载**：在生产环境下挂载 Navbar 和主内容区域\n3. **底部信息**：显示构建信息和版权声明\n4. **追踪像素**：集成 Scarf 分析工具\n\n```mermaid\ngraph TD\n    A[page.tsx] --> B{production 环境}\n    B -->|Demo| C[隐藏导航栏]\n    B -->|非 Demo| D[显示 NavbarComponent]\n    D --> E[显示主内容区域]\n    E --> F[Footer + 追踪像素]\n    \n    G[GettingStarted 检测] --> H{localStorage}\n    H -->|首次| I[显示引导弹窗]\n    H -->|非首次| J[跳过]\n```\n\n## 数据流与状态管理\n\n### 组件间通信模式\n\nVerba 前端采用以下状态管理模式：\n\n| 模式 | 使用场景 | 示例 |\n|-----|---------|------|\n| Props 向下传递 | 父子组件数据共享 | ChatMessage 接收 message prop |\n| useState | 组件内部状态 | selectedFileData, currentPage |\n| useRef | 可变引用避免重渲染 | isFetching |\n| 回调函数向上传递 | 子向父组件通信 | setCurrentPage, setSelectedDocument |\n\n### API 通信\n\n前端通过 `frontend/app/api.ts` 定义的 API 函数与后端通信，包括：\n\n- 认证与部署配置\n- 文档操作（CRUD）\n- RAG 配置获取与更新\n- 系统状态查询\n\nWebSocket 连接用于实时聊天消息传输和导入进度更新。\n\n## 样式系统\n\n### Verba 主题变量\n\n应用定义了统一的颜色变量系统，以 `-verba` 后缀区分：\n\n| 变量类名 | 用途 |\n|---------|------|\n| text-text-verba | 主文本颜色 |\n| text-text-alt-verba | 次要文本颜色 |\n| bg-bg-verba | 主背景色 |\n| bg-bg-alt-verba | 次要背景色 |\n| bg-primary-verba | 主色调 |\n| bg-button-verba | 按钮默认色 |\n| bg-button-hover-verba | 按钮悬停色 |\n| bg-warning-verba | 警告/错误色 |\n\n资料来源：[frontend/app/components/Chat/ChatMessage.tsx:20-30](), [frontend/app/components/Settings/InfoView.tsx:1-50]()\n\n### 响应式设计\n\n应用采用移动优先的响应式设计策略：\n\n| 断点 | 标识 | 适用场景 |\n|-----|------|---------|\n| < 768px | 默认/sm | 移动端导航、隐藏元素 |\n| ≥ 768px | md | 桌面端导航显示、汉堡菜单隐藏 |\n| ≥ 1024px | lg | 大屏布局调整 |\n\n## 总结\n\nVerba 前端采用组件化、模块化的架构设计，通过清晰的功能划分实现聊天、文档管理、数据导入和系统设置等核心功能。组件间通过 props、回调函数和 React Hooks 进行状态管理，样式系统基于 Tailwind CSS 和 daisyUI 提供一致的用户体验。\n\n---\n\n<a id='page-backend-components'></a>\n\n## 后端组件系统\n\n### 相关页面\n\n相关主题：[系统整体架构](#page-architecture), [模型集成](#page-model-integration), [数据导入与处理](#page-data-ingestion)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [goldenverba/components/interfaces.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/interfaces.py)\n- [goldenverba/components/managers.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/managers.py)\n- [goldenverba/components/types.py](https://github.com/weave/Verba/blob/main/goldenverba/components/types.py)\n- [goldenverba/components/__init__.py](https://github.com/weaviate/Verba/blob/main/goldenverba/components/__init__.py)\n- [goldenverba/verba_manager.py](https://github.com/weaviate/Verba/blob/main/goldenverba/verba_manager.py)\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- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n</details>\n\n# 后端组件系统\n\nVerba 是一个开源的 RAG（检索增强生成）应用，其后端采用模块化的组件系统设计。该系统通过标准化的接口定义和统一的管理机制，支持多种 Reader（读取器）、Embedder（嵌入器）、Generator（生成器）和 Retriever（检索器）的灵活组合与配置。\n\n## 系统架构概述\n\nVerba 的后端组件系统基于 Python 实现，采用面向接口的编程范式。核心组件类型包括：\n\n| 组件类型 | 功能描述 | 支持的提供商示例 |\n|---------|---------|-----------------|\n| Reader | 文档读取与解析 | AssemblyAI、URL Reader、Default Reader |\n| Embedder | 文本向量化嵌入 | Ollama、OpenAI、Upstage |\n| Generator | LLM 响应生成 | OpenAI、Anthropic、Cohere、Novita、Upstage、Groq |\n| Retriever | 语义检索功能 | Weaviate 原生检索 |\n\n该系统通过 `goldenverba/components/` 目录下的模块进行组织，所有组件均实现统一的接口规范，从而保证系统的可扩展性和可维护性。资料来源：[setup.py:1-15]()\n\n## 核心类型定义\n\n### Document 数据模型\n\nDocument 是系统中最核心的数据单元，用于表示待处理的文档或文本内容：\n\n```python\nDocument(\n    title=str,           # 文档标题\n    content=str,         # 文档内容\n    extension=str,       # 文件扩展名\n    labels=list,         # 标签列表\n    source=str,          # 原始来源链接\n    fileSize=str,        # 文件大小\n    metadata=dict,       # 元数据\n    meta=dict            # 配置元数据\n)\n```\n\n文档创建可通过 `create_document()` 函数完成，该函数接收文件内容 `content` 和 `FileConfig` 配置对象，返回完整的 Document 实例。资料来源：[goldenverba/components/document.py:40-49]()\n\n### FileConfig 配置模型\n\nFileConfig 用于配置单个文件的导入设置：\n\n```python\nFileConfig(\n    filename=str,        # 文件名\n    extension=str,       # 扩展名\n    labels=list,         # 文件标签\n    source=str,          # 来源链接\n    file_size=str,       # 文件大小\n    metadata=str,        # 元数据字符串\n)\n```\n\n### 组件类型枚举\n\n系统定义了标准化的组件类型枚举，用于区分不同功能的组件：\n\n| 枚举值 | 组件类型 | 用途 |\n|-------|---------|------|\n| `READER` | 读取器 | 解析和加载各种格式的文档 |\n| `EMBEDDER` | 嵌入器 | 将文本转换为向量表示 |\n| `GENERATOR` | 生成器 | 调用 LLM 生成响应 |\n| `RETRIEVER` | 检索器 | 执行语义检索操作 |\n\n## 组件接口规范\n\nVerba 采用面向接口的设计原则，所有组件必须实现相应的抽象接口。接口定义确保了组件之间的解耦，使得添加新的提供商实现变得简单高效。\n\n### 组件生命周期\n\n```mermaid\ngraph TD\n    A[初始化组件] --> B[加载配置]\n    B --> C[建立连接]\n    C --> D[执行操作]\n    D --> E[返回结果]\n    E --> F[释放资源]\n```\n\n组件的典型生命周期包括：初始化、配置加载、连接建立、执行具体操作、结果返回和资源释放。每一步都遵循统一的错误处理机制。\n\n## 环境变量配置\n\nVerba 支持通过环境变量配置组件行为，以下是主要配置项：\n\n| 环境变量 | 用途 | 说明 |\n|---------|------|------|\n| `DEFAULT_DEPLOYMENT` | 部署类型 | 可设为 Local、Docker、Weaviate 或 Custom |\n| `OLLAMA_MODEL` | Ollama 模型 | 指定 Ollama 使用的模型名称 |\n| `OLLAMA_EMBED_MODEL` | Ollama 嵌入模型 | 指定 Ollama 嵌入使用的模型 |\n| `PORT` | 服务端口 | 自定义 Verba 服务监听端口 |\n\n这些环境变量允许用户在启动前预先配置组件，减少前端交互中的配置负担。资料来源：[CHANGELOG.md:8-12]()\n\n## 支持的组件提供商\n\n### 已集成的生成器\n\n| 提供商 | 说明 | 资料来源 |\n|-------|------|---------|\n| OpenAI | GPT 系列模型 | setup.py |\n| Anthropic | Claude 系列模型 | LoginView.tsx |\n| Cohere | Command R 系列 | LoginView.tsx |\n| Upstage | 韩国 Upstage AI | CHANGELOG.md |\n| Novita | Novita AI 服务 | CHANGELOG.md |\n| Groq | Groq 云服务 | CHANGELOG.md |\n\n### 已集成的嵌入器\n\n系统支持多种嵌入模型集成，包括本地 Ollama 模型和云服务提供商的模型。通过统一接口封装，切换不同的嵌入提供商只需修改配置而无需更改业务代码。\n\n### 已集成的读取器\n\n| 读取器 | 支持格式 | 说明 |\n|-------|---------|------|\n| DefaultReader | csv、xlsx、xls、txt 等 | 默认文档读取器 |\n| AssemblyAI | 音频文件 | 通过 AssemblyAI 服务转录音频 |\n| URL Reader | 网页内容 | 从 URL 抓取网页文本 |\n\n版本 2.1.3 新增了对 CSV、Excel 格式的原生支持，扩展了文档处理的覆盖范围。资料来源：[CHANGELOG.md:12]()\n\n## 组件管理器\n\n组件管理器（Managers）负责组件的注册、发现和生命周期管理。它维护了系统中所有可用组件的目录，并提供组件实例化、配置更新和状态监控的功能。\n\n```mermaid\ngraph LR\n    A[前端请求] --> B[Verba Manager]\n    B --> C[组件选择]\n    C --> D[配置应用]\n    D --> E[组件执行]\n    E --> F[结果返回]\n```\n\n### 管理器核心职责\n\n- **组件注册**：将新组件注册到系统中\n- **配置管理**：维护各组件的配置状态\n- **依赖解析**：处理组件间的依赖关系\n- **资源分配**：管理组件使用的计算资源\n\n## 部署模式与组件关系\n\nVerba 支持四种部署模式，不同模式下启用的组件有所不同：\n\n| 部署模式 | 特性 | 适用场景 |\n|---------|------|---------|\n| Local | 本地 Ollama 或远程 LLM | 开发测试 |\n| Docker | 容器化部署 | 生产环境 |\n| Weaviate | Weaviate Cloud | 云端托管 |\n| Custom | 自定义 Weaviate 实例 | 企业内部部署 |\n\n在 Demo 模式下，部分管理功能（如 Import Data、Settings）会被隐藏，仅保留核心的 Chat 功能。资料来源：[NavbarComponent.tsx:15-30]()\n\n## 前端配置交互\n\n前端通过标准化接口与后端组件系统交互，主要涉及以下配置文件：\n\n```typescript\ninterface RAGConfig {\n    \"Reader\": { components: Record<string, ComponentConfig> };\n    \"Embedder\": { components: Record<string, ComponentConfig> };\n    \"Generator\": { components: Record<string, ComponentConfig> };\n    \"Retriever\": { components: Record<string, ComponentConfig> };\n}\n```\n\n前端组件如 `ChatConfig.tsx` 负责渲染各组件的配置界面，用户可以动态选择和配置 Reader、Embedder、Generator 和 Retriever。资料来源：[ChatConfig.tsx:20-40]()\n\n## 版本演进\n\n| 版本 | 主要变更 |\n|------|---------|\n| 2.1.3 | 新增 OLLAMA 环境变量支持；扩展 DefaultReader 支持 xlsx/xls/csv |\n| 2.1.2 | 新增 Novita 生成器；添加文档类基础测试 |\n| 2.1.1 | 动态模型名称获取 |\n| 2.1.0 | 新增 Upstage 全套组件；Groq 集成；AssemblyAI 音频读取器 |\n\n组件系统的持续演进体现了 Verba 对多提供商支持和格式兼容性的重视。\n\n## 开发指南\n\n### 添加新组件\n\n1. 在 `goldenverba/components/` 下创建新的组件文件\n2. 实现统一的组件接口\n3. 在组件管理器中注册新组件\n4. 在前端添加对应的配置界面\n\n### 配置验证\n\n系统启动时会验证环境变量和 API Key 的有效性。建议使用 `.env` 文件集中管理敏感配置，Verba 会自动读取并应用这些配置。\n\n---\n\n<a id='page-data-ingestion'></a>\n\n## 数据导入与处理\n\n### 相关页面\n\n相关主题：[后端组件系统](#page-backend-components), [RAG 检索与生成流程](#page-rag-pipeline), [环境变量与配置](#page-configuration)\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- [frontend/app/components/Ingestion/FileSelectionView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/FileSelectionView.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/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n- [frontend/app/components/Document/ChunkView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Document/ChunkView.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# 数据导入与处理\n\n## 概述\n\nVerba 的数据导入与处理模块是 RAG（检索增强生成）流水线的核心入口，负责将各类数据源（文件、目录、URL）摄入系统并进行预处理。该模块支持多种文件格式的读取、文档分块（Chunking）、向量化（Embedding）等关键步骤，最终将处理后的数据存储至 Weaviate 向量数据库中。\n\n从 CHANGELOG.md 的记录可知，Verba 2.1.3 版本已添加对 `csv`、`xlsx`、`xls` 格式的支持，显著扩展了数据导入的灵活性。资料来源：[CHANGELOG.md:10-12]()\n\n## 核心架构\n\nVerba 的数据处理采用模块化 RAG 配置架构，每个文档可独立配置 Reader、Chunker、Embedder 组件。这种设计允许用户根据不同数据类型选择最优的处理策略。\n\n```mermaid\ngraph TD\n    A[用户导入数据] --> B[Reader 组件]\n    B --> C[Chunker 分块]\n    C --> D[Embedder 向量化]\n    D --> E[Weaviate 存储]\n    \n    F[文件/目录/URL] --> B\n    G[元数据配置] --> E\n    H[标签管理] --> E\n```\n\n## 数据导入流程\n\n### 导入方式\n\nVerba 前端界面提供了三种数据导入方式，分别对应不同的使用场景：\n\n| 导入方式 | 适用场景 | 处理逻辑 |\n|---------|---------|---------|\n| Add Files | 单文件或少量文件上传 | 直接读取文件内容 |\n| Add Directory | 批量导入文件夹 | 遍历目录下的所有支持文件 |\n| Add URL | 网页内容抓取 | 通过 URL Reader 解析网页 |\n\n资料来源：[README.md:28-32]()\n\n### 导入界面组件\n\n前端 `NavbarComponent.tsx` 中的导航栏提供了 \"Import Data\" 入口，该入口仅在非 Demo 模式下显示：\n\n```typescript\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\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:45-54]()\n\n## 文件配置选项\n\n在 `BasicSettingView.tsx` 中，Verba 提供了丰富的文件配置选项，每个文件可独立设置以下参数：\n\n### 基本信息配置\n\n| 配置项 | 说明 | 数据类型 |\n|-------|------|---------|\n| Title | 文档标题 | 字符串 |\n| Source Link | 原始数据来源链接 | URL 字符串 |\n| Labels | 文档标签，用于分类检索 | 字符串数组 |\n| Metadata | 元数据，影响检索和生成结果 | JSON 字符串 |\n| Overwrite | 是否覆盖同名文档 | 布尔值 |\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:28-70]()\n\n### 标签管理\n\n用户可以通过输入框添加标签，按 Enter 键或点击 Add 按钮即可添加标签到当前文档：\n\n```typescript\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```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:36-48]()\n\n### 元数据配置\n\n元数据以 JSON 格式存储，会被添加到发送给 Embedder 和 Generator 的上下文中，从而影响检索和生成结果：\n\n```typescript\n<textarea\n  className=\"grow w-full textarea flex items-center gap-2 max-h-64 bg-bg-verba\"\n  value={metadata}\n  onChange={handleMetadataChange}\n/>\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:93-98]()\n\n## RAG 组件配置\n\n每个导入的文件都可以独立配置其 RAG 流水线中的关键组件：\n\n### Chunker 分块器\n\n用于将长文档切分为适合检索的较小单元。分块策略直接影响后续检索的质量和上下文完整性。\n\n### Embedder 向量化器\n\n负责将文本内容转换为向量表示，存储至 Weaviate 以支持语义检索。\n\n```typescript\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:148-160]()\n\n## 文档对象模型\n\n`Document` 类是 Verba 中数据表示的核心结构，定义在 `goldenverba/components/document.py` 中：\n\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资料来源：[goldenverba/components/document.py:56-68]()\n\nDocument 对象包含以下核心字段：\n\n| 字段 | 说明 |\n|-----|------|\n| title | 文档标题 |\n| content | 文档原始内容 |\n| extension | 文件扩展名 |\n| labels | 标签数组 |\n| source | 来源链接 |\n| fileSize | 文件大小 |\n| metadata | 元数据字符串 |\n| chunks | 分块后的数据列表 |\n\n## 分块查看器\n\n导入后的文档可以通过 Document Explorer 查看其分块内容。`ChunkView.tsx` 组件负责渲染和导航分块：\n\n```typescript\n<div className=\"flex gap-2 items-center p-3 bg-secondary-verba rounded-full w-fit\">\n  <IoNewspaper size={12} />\n  <p className=\"text-xs flex text-text-verba\">\n    Chunk {chunks[currentChunkIndex].chunk_id}\n  </p>\n</div>\n```\n\n资料来源：[frontend/app/components/Document/ChunkView.tsx:28-34]()\n\n### 分块导航\n\n支持 Previous 和 Next 按钮进行分块间的导航切换：\n\n```typescript\n<VerbaButton\n  title={\"Previous \" + (chunkScores ? \"Chunk\" : \"Page\")}\n  onClick={previousPage}\n/>\n<VerbaButton\n  title={\"Next \" + (chunkScores ? \"Chunk\" : \"Page\")}\n  onClick={nextPage}\n/>\n```\n\n资料来源：[frontend/app/components/Document/ContentView.tsx:52-68]()\n\n## 文件导入流程图\n\n```mermaid\ngraph LR\n    A[选择导入方式] --> B{导入类型}\n    B -->|文件| C[上传文件]\n    B -->|目录| D[选择目录]\n    B -->|URL| E[输入URL]\n    \n    C --> F[配置Reader组件]\n    D --> F\n    E --> F\n    \n    F --> G[配置Chunker]\n    G --> H[配置Embedder]\n    H --> I[设置元数据]\n    \n    I --> J[点击Import Selected]\n    J --> K[后端处理]\n    K --> L[存入Weaviate]\n    L --> M[导入完成]\n```\n\n## 环境变量配置\n\nVerba 支持通过 `.env` 文件预配置导入相关的环境变量，无需在界面中重复输入：\n\n| 环境变量 | 说明 |\n|---------|------|\n| OLLAMA_MODEL | Ollama 使用的模型名称 |\n| OLLAMA_EMBED_MODEL | Ollama 嵌入模型名称 |\n\n资料来源：[CHANGELOG.md:8-9]()\n\n## 依赖项\n\n数据导入模块依赖以下核心 Python 包，定义在 `setup.py` 中：\n\n| 包名 | 版本 | 用途 |\n|-----|------|-----|\n| weaviate-client | 4.9.6 | 向量数据库交互 |\n| openpyxl | 3.1.5 | Excel 文件处理 |\n| xlrd | 2.0.1 | 旧版 Excel 读取 |\n\n资料来源：[setup.py:18-23]()\n\n## 最佳实践\n\n### 文件命名\n\n建议为文档设置有意义的标题，便于后续在 Document Explorer 中识别和检索。系统会自动为 URL 类型的内容使用其 URL 作为默认文件名。\n\n### 元数据使用\n\n合理使用元数据可以显著提升检索精度。元数据会被添加到上下文请求中，影响嵌入和生成结果。建议添加文档来源、时间、作者等关键信息。\n\n### 标签管理\n\n使用一致的标签体系有助于组织大量文档。标签可用于快速过滤和分组相关文档。\n\n### 分块策略选择\n\n根据文档类型选择合适的分块策略。长文档建议使用语义分块（Semantic Chunking），短文档可使用固定长度分块。\n\n---\n\n<a id='page-rag-pipeline'></a>\n\n## RAG 检索与生成流程\n\n### 相关页面\n\n相关主题：[模型集成](#page-model-integration), [数据导入与处理](#page-data-ingestion), [前端架构与组件](#page-frontend-structure)\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- [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- [frontend/app/components/Ingestion/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.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/Navigation/NavbarComponent.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Navigation/NavbarComponent.tsx)\n- [frontend/app/components/Settings/InfoView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Settings/InfoView.tsx)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n</details>\n\n# RAG 检索与生成流程\n\n## 概述\n\nVerba 是一个开源的 RAG（Retrieval-Augmented Generation，检索增强生成）应用，名为 \"Golden RAGtriever\"。该项目由 Weaviate 团队开发，旨在为检索增强生成应用提供流线型、用户友好的界面。Verba 允许用户通过几个简单步骤深入数据并进行有意义的交互。\n\nRAG 流程是 Verba 的核心功能，它将文档检索与语言模型生成相结合，使用户能够针对自己的数据提出问题并获得基于上下文的答案。\n\n## 系统架构\n\n```mermaid\ngraph TD\n    A[用户提问] --> B[Chat Interface]\n    B --> C{检索阶段}\n    C --> D[Embedder 嵌入向量]\n    D --> E[Weaviate 向量数据库]\n    E --> F[Retriever 检索相关 Chunk]\n    F --> G{生成阶段}\n    G --> H[Generator 生成模型]\n    H --> I[返回答案与上下文]\n    \n    J[数据导入] --> K[Reader 读取文件]\n    K --> L[Chunker 分块处理]\n    L --> M[Embedder 向量化]\n    M --> E\n```\n\n## 核心组件\n\n### 组件配置架构\n\nVerba 的 RAG 管道由三个核心组件构成，通过 `ChatConfig` 组件进行统一配置管理：\n\n| 组件类型 | 功能描述 | 配置位置 |\n|---------|---------|---------|\n| **Embedder** | 将文本转换为向量嵌入 | 检索阶段 |\n| **Retriever** | 从向量数据库检索相关文档块 | 检索阶段 |\n| **Generator** | 基于检索结果生成最终答案 | 生成阶段 |\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:33-48]()\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<ComponentView\n  RAGConfig={RAGConfig}\n  component_name=\"Generator\"\n  selectComponent={selectComponent}\n  updateConfig={updateConfig}\n  saveComponentConfig={saveComponentConfig}\n  blocked={production == \"Demo\"}\n/>\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## 检索流程详解\n\n### 向量化与存储\n\n用户导入的文档经过以下处理流程进入系统：\n\n1. **文档读取**：通过 Reader 组件读取多种格式的文件（包括 `csv`、`xlsx`、`xls` 等）\n2. **文档创建**：使用 `Document` 类封装文档元数据\n3. **分块处理**：将文档切分为适合检索的文本块（Chunks）\n4. **向量化存储**：通过 Embedder 将文本块转换为向量，存储于 Weaviate 向量数据库\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:60-70]()\n资料来源：[goldenverba/components/document.py:42-53]()\n\n### 检索过程\n\n```mermaid\ngraph LR\n    A[用户问题] --> B[Query 向量化]\n    B --> C[向量相似度搜索]\n    C --> D[Top-K 检索]\n    D --> E[返回相关 Chunks]\n    E --> F[传递给 Generator]\n```\n\n当用户在 Chat 界面输入问题时，系统执行以下步骤：\n\n1. **问题向量化**：用户输入的查询文本通过 Embedder 转换为查询向量\n2. **向量搜索**：在 Weaviate 中执行向量相似度搜索\n3. **结果排序**：根据相似度得分返回最相关的 K 个文档块\n4. **状态展示**：前端显示 \"Retrieving...\" 状态提示\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:8-15]()\n\n```tsx\n<p className=\"text-text-alt-verba\">\n  {fetchingStatus === \"CHUNKS\" && \"Retrieving...\"}\n  {fetchingStatus === \"RESPONSE\" && \"Generating...\"}\n</p>\n```\n\n## 生成流程详解\n\n### 上下文增强的生成\n\n检索到的文档块（Chunks）与用户问题一起作为上下文传递给 Generator 组件：\n\n```mermaid\ngraph TD\n    A[用户问题] --> E\n    B[检索到的 Chunks] --> E\n    E[上下文组装] --> F[Prompt 构建]\n    F --> G[LLM 生成]\n    G --> H[返回答案]\n```\n\nGenerator 组件支持多种大语言模型提供者，包括：\n\n- **OpenAI**（支持动态模型名称获取）\n- **Ollama**（支持 `OLLAMA_MODEL` 和 `OLLAMA_EMBED_MODEL` 环境变量配置）\n- **Novita**\n- **Upstage**\n- **Groq**\n- **Anthropic**（通过 Ollama 或 LLM 提供商）\n\n资料来源：[CHANGELOG.md:6-15]()\n\n### 响应状态管理\n\n生成过程中的状态通过 `fetchingStatus` 状态机管理：\n\n| 状态值 | 含义 | UI 显示 |\n|-------|------|--------|\n| `IDLE` | 空闲状态 | 正常输入框 |\n| `CHUNKS` | 正在检索文档块 | \"Retrieving...\" |\n| `RESPONSE` | 正在生成响应 | \"Generating...\" |\n| `DONE` | 完成 | 显示结果 |\n\n用户可以通过取消按钮随时终止检索或生成过程：\n\n```tsx\n<button\n  onClick={() => {\n    setFetchingStatus(\"DONE\");\n    isFetching.current = false;\n  }}\n  className=\"btn btn-circle btn-sm bg-bg-alt-verba hover:bg-warning-verba...\"\n>\n  <MdCancel size={15} />\n</button>\n```\n\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:16-24]()\n\n## 数据模型\n\n### Document 类结构\n\n```python\nclass Document:\n    def __init__(\n        self,\n        title: str,           # 文档标题\n        content: str,         # 文档内容\n        extension: str,       # 文件扩展名\n        labels: List[str],    # 标签列表\n        source: str,          # 源链接\n        fileSize: int,        # 文件大小\n        metadata: str,        # 元数据\n        meta: Dict,           # 额外元数据\n    )\n```\n\n文档对象在导入时通过 `create_document` 函数创建，该函数将文件内容与 `FileConfig` 配置结合生成完整的文档对象。\n\n资料来源：[goldenverba/components/document.py:1-53]()\n\n### 文件配置结构\n\n导入文件时，系统为每个文件维护独立的配置状态：\n\n```tsx\ninterface FileData {\n  content: string;           // 文件内容\n  rag_config: RAGConfig;     // RAG 组件配置\n  block: boolean;            // 是否阻塞\n  filename: string;         // 文件名/标题\n  source: string;           // 源链接\n  labels: string[];         // 标签\n  metadata: object;         // 元数据\n}\n```\n\n每个文件可以独立配置 Reader、Embedder、Generator 等组件，实现灵活的管道定制。\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-80]()\n\n## 部署模式\n\nVerba 支持多种部署方式，RAG 流程的配置也会相应调整：\n\n| 部署模式 | 说明 | RAG 配置限制 |\n|---------|------|-------------|\n| **Local** | 本地 Weaviate 实例 | 完全可配置 |\n| **Docker** | Docker 容器部署 | 完全可配置 |\n| **Weaviate Cloud** (WCS) | 云端托管服务 | 完全可配置 |\n| **Custom** | 自定义 Weaviate 实例 | 完全可配置 |\n| **Demo** | 演示模式 | 配置不可修改 |\n\n可通过 `DEFAULT_DEPLOYMENT` 环境变量设置默认部署类型。\n\n资料来源：[frontend/app/components/Login/LoginView.tsx:15-30]()\n资料来源：[README.md:1-30]()\n\n## 用户交互界面\n\n### 导航与页面结构\n\nVerba 前端采用单页应用架构，主要导航入口包括：\n\n```mermaid\ngraph TD\n    A[Navbar] --> B[Chat 页面]\n    A --> C[Documents 页面]\n    A --> D[Import Data 页面]\n    A --> E[Settings 页面]\n    \n    B --> B1[对话输入]\n    B --> B2[聊天历史]\n    B --> B3[配置面板]\n    \n    C --> C1[文档列表]\n    C --> C2[内容查看器]\n    C --> C3[向量可视化]\n```\n\n导航组件根据部署环境动态显示菜单项：\n\n```tsx\n{production != \"Demo\" && (\n  <li key={\"Menu Button4\"}>\n    <a onClick={() => setCurrentPage(\"ADD\")}>Import Data</a>\n  </li>\n)}\n```\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:1-50]()\n\n### 文档浏览与 Chunk 导航\n\n在 Documents 页面中，用户可以浏览已导入的文档内容，并按 Chunk 分页查看：\n\n```tsx\n<VerbaButton\n  title={\"Previous \" + (chunkScores ? \"Chunk\" : \"Page\")}\n  onClick={previousPage}\n/>\n<p className=\"text-xs text-text-verba\">\n  {chunkScores ? \"Chunk \" : \"Page \"} {page}\n</p>\n<VerbaButton\n  title={\"Next \" + (chunkScores ? \"Chunk\" : \"Page\")}\n  onClick={nextPage}\n/>\n```\n\n资料来源：[frontend/app/components/Document/ContentView.tsx:40-55]()\n\n## 核心技术栈\n\n| 层级 | 技术选型 | 版本要求 |\n|-----|---------|---------|\n| **后端框架** | FastAPI | 0.111.1 |\n| **向量数据库客户端** | weaviate-client | 4.9.6 |\n| **服务器** | Uvicorn + Gunicorn | 0.29.0 / 22.0.0 |\n| **前端框架** | React (Next.js) | - |\n| **UI 组件库** | daisyUI + Tailwind CSS | - |\n| **Python 版本** | 3.10 - 3.12 | - |\n\n资料来源：[setup.py:1-30]()\n\n## 配置管理\n\n### 运行时配置重置\n\nSettings 页面提供多种重置功能，用于管理 RAG 系统状态：\n\n| 功能 | 说明 | 影响范围 |\n|-----|------|---------|\n| **Reset Documents** | 清除所有文档和 Chunk | 文档数据 |\n| **Reset Config** | 重置 RAG 组件配置 | 配置状态 |\n| **Reset Verba** | 删除所有 Verba 相关集合 | 全部数据 |\n| **Reset Suggestions** | 清除自动补全建议 | 用户偏好 |\n\n```tsx\n<UserModalComponent\n  modal_id=\"reset-documents\"\n  title=\"Reset Documents\"\n  text=\"Are you sure you want to reset all documents? This will clear all documents and chunks from Verba.\"\n  triggerAccept={resetDocuments}\n  triggerString=\"Reset\"\n/>\n```\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:1-50]()\n\n## 总结\n\nVerba 的 RAG 检索与生成流程是一个端到端的智能问答系统：\n\n1. **数据导入阶段**：文档通过 Reader 读取、Chunker 分块、Embedder 向量化后存入 Weaviate\n2. **检索阶段**：用户问题通过 Embedder 向量化，在向量数据库中执行相似度搜索返回相关 Chunks\n3. **生成阶段**：检索结果与问题组装为 Prompt，传递给 Generator（LLM）生成最终答案\n4. **展示阶段**：答案与相关上下文在 Chat 界面展示，支持用户继续交互\n\n整个流程高度可配置，支持多种部署模式和多种大语言模型提供商，满足不同场景下的 RAG 应用需求。\n\n---\n\n<a id='page-model-integration'></a>\n\n## 模型集成\n\n### 相关页面\n\n相关主题：[后端组件系统](#page-backend-components), [RAG 检索与生成流程](#page-rag-pipeline), [环境变量与配置](#page-configuration)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\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/BasicSettingView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Ingestion/BasicSettingView.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/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- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n</details>\n\n# 模型集成\n\n## 概述\n\n模型集成是 Verba（Golden RAGtriever）系统的核心功能模块，负责管理和协调 RAG（检索增强生成）管道中的三类关键组件：**嵌入模型（Embedder）**、**生成模型（Generator）** 和 **检索器（Retriever）**。通过标准化的组件接口设计，Verba 支持灵活接入多种大语言模型提供商和嵌入服务，实现端到端的向量检索与生成式问答功能。\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:35-45]()\n\n## 架构设计\n\n### 组件层次结构\n\nVerba 的模型集成采用模块化架构，各组件通过统一的配置接口进行管理：\n\n```mermaid\ngraph TD\n    subgraph \"RAG 配置层\"\n        RAGConfig[RAGConfig 配置对象]\n    end\n    \n    subgraph \"嵌入层 Embedder\"\n        OpenAI_Emb[OpenAI Embedder]\n        Cohere_Emb[Cohere Embedder]\n        Ollama_Emb[Ollama Embedder]\n    end\n    \n    subgraph \"生成层 Generator\"\n        OpenAI_Gen[OpenAI Generator]\n        Anthropic_Gen[Anthropic Generator]\n        Gemini_Gen[Gemini Generator]\n        Groq_Gen[Groq Generator]\n        Novita_Gen[Novita Generator]\n        Upstage_Gen[Upstage Generator]\n    end\n    \n    subgraph \"检索层 Retriever\"\n        BM25_R[BM25 Retriever]\n        Vector_R[Vector Retriever]\n        Hybrid_R[Hybrid Retriever]\n    end\n    \n    RAGConfig --> OpenAI_Emb\n    RAGConfig --> OpenAI_Gen\n    RAGConfig --> BM25_R\n    \n    style RAGConfig fill:#f9f,stroke:#333,stroke-width:2px\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:50-60]()\n\n### 集成流程\n\n模型集成的完整工作流程包括配置选择、内容处理、向量嵌入和生成响应四个阶段：\n\n```mermaid\ngraph LR\n    A[用户选择组件配置] --> B[加载嵌入模型]\n    B --> C[加载生成模型]\n    C --> D[文档分块 Chunker]\n    D --> E[向量嵌入 Embedding]\n    E --> F[存储至向量数据库]\n    F --> G[用户查询]\n    G --> H[检索相关块]\n    H --> I[上下文组装]\n    I --> J[生成响应]\n```\n\n## 支持的模型提供商\n\n### 嵌入模型（Embedder）\n\nVerba 支持多种嵌入模型服务，通过 `OLLAMA_EMBED_MODEL` 等环境变量进行配置。\n\n| 提供商 | 类型 | 配置方式 | 状态 |\n|--------|------|----------|------|\n| OpenAI | Embedder | API Key + Model Name | 稳定 |\n| Cohere | Embedder | API Key + Model Name | 稳定 |\n| Ollama | Embedder | 本地模型 + URL | 稳定 |\n| Upstage | Embedder | API Key + Model Name | 稳定 |\n\n资料来源：[CHANGELOG.md:7-8]()\n\n### 生成模型（Generator）\n\n生成器组件支持多种大语言模型提供商，系统会根据 API 凭证动态获取模型名称。\n\n| 提供商 | 组件类 | 特点 | 添加版本 |\n|--------|--------|------|----------|\n| OpenAI | OpenAI Generator | 动态模型名称获取 | 稳定 |\n| Anthropic | Anthrophic Generator | 支持 Claude 系列 | 稳定 |\n| Gemini | Gemini Generator | Google 生成式 AI | 稳定 |\n| Groq | Groq Generator | 低延迟推理 | 2.1.0+ |\n| Novita | Novita Generator | 新型提供商 | 2.1.2+ |\n| Upstage | Upstage Generator | 综合型解决方案 | 2.1.0+ |\n\n资料来源：[CHANGELOG.md:15-16]()\n\n### 检索器（Retriever）\n\n检索器负责从向量数据库中获取相关内容，支持多种检索策略。\n\n## 配置管理\n\n### RAGConfig 结构\n\nRAGConfig 是管理所有组件配置的核心对象，采用组件名称作为键值：\n\n```typescript\ninterface RAGConfig {\n  \"Embedder\": {\n    selected: string;          // 当前选中的嵌入器名称\n    components: {\n      [key: string]: {\n        name: string;\n        type: string;\n        description: string;\n        models?: string[];    // 可用模型列表\n      }\n    }\n  };\n  \"Generator\": {\n    selected: string;\n    components: {\n      [key: string]: {\n        name: string;\n        type: string;\n        description: string;\n      }\n    }\n  };\n  \"Retriever\": {\n    selected: string;\n    components: {\n      [key: string]: {\n        name: string;\n        type: string;\n        description: string;\n      }\n    }\n  };\n}\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:30-45]()\n\n### 环境变量配置\n\nVerba 支持通过环境变量配置模型集成参数：\n\n| 环境变量 | 用途 | 示例值 |\n|----------|------|--------|\n| `OLLAMA_MODEL` | Ollama 生成模型 | `llama2` |\n| `OLLAMA_EMBED_MODEL` | Ollama 嵌入模型 | `nomic-embed-text` |\n| `OPENAI_API_KEY` | OpenAI API 密钥 | `sk-...` |\n| `ANTHROPIC_API_KEY` | Anthropic API 密钥 | `sk-ant-...` |\n\n资料来源：[CHANGELOG.md:7-8]()\n\n## 前端配置界面\n\n### ChatConfig 组件\n\nChatConfig 组件提供交互式界面，用于配置 RAG 管道中的三类核心组件：\n\n```tsx\n<div className=\"flex flex-col justify-start gap-3 rounded-2xl w-full p-6\">\n  <ComponentView\n    RAGConfig={RAGConfig}\n    component_name=\"Embedder\"\n    selectComponent={selectComponent}\n    updateConfig={updateConfig}\n    saveComponentConfig={saveComponentConfig}\n    blocked={production == \"Demo\"}\n  />\n  <ComponentView\n    RAGConfig={RAGConfig}\n    component_name=\"Generator\"\n    selectComponent={selectComponent}\n    updateConfig={updateConfig}\n    saveComponentConfig={saveComponentConfig}\n    blocked={production == \"Demo\"}\n  />\n  <ComponentView\n    RAGConfig={RAGConfig}\n    component_name=\"Retriever\"\n    selectComponent={selectComponent}\n    updateConfig={updateConfig}\n    saveComponentConfig={saveComponentConfig}\n    blocked={production == \"Demo\"}\n  />\n</div>\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:35-55]()\n\n### 组件选择机制\n\n组件选择通过 `selectComponent` 函数处理，该函数更新 `RAGConfig` 中的 `selected` 字段：\n\n```mermaid\nsequenceDiagram\n    participant User as 用户\n    participant UI as ChatConfig UI\n    participant State as 状态管理\n    participant Backend as 后端 API\n    \n    User->>UI: 选择组件下拉菜单\n    UI->>State: 调用 selectComponent()\n    State->>Backend: 更新 RAGConfig\n    Backend-->>State: 返回更新后的配置\n    State-->>UI: 刷新组件视图\n```\n\n### 配置保存与重置\n\n系统提供两种配置操作：\n\n- **保存配置（onSave）**：将当前 RAGConfig 持久化至后端\n- **重置配置（onReset）**：将配置恢复至默认值\n\n```tsx\n<VerbaButton\n  title=\"Save Config\"\n  onClick={onSave}\n  disabled={production == \"Demo\"}\n/>\n<VerbaButton\n  title=\"Reset Config\"\n  onClick={onReset}\n  disabled={production == \"Demo\"}\n/>\n```\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx:20-30]()\n\n## 内容处理流程\n\n### 文档导入配置\n\n在文档导入阶段，用户可配置以下处理组件：\n\n| 组件 | 作用 | 配置项 |\n|------|------|--------|\n| **Reader** | 读取文档内容 | 支持 PDF、CSV、XLSX、XLS 等格式 |\n| **Chunker** | 文档分块 | 控制块大小和重叠 |\n| **Embedder** | 向量嵌入 | 生成文档向量表示 |\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:1-20]()\n\n### 嵌入配置界面\n\n嵌入器配置显示当前选中的嵌入器及其描述信息：\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:60-72]()\n\n### 调试功能\n\n系统提供调试模式，允许用户查看完整的文件配置 JSON：\n\n```tsx\n<div className=\"flex gap-2 justify-between items-center text-text-verba\">\n  <p className=\"flex min-w-[8vw]\">Debug</p>\n  <VerbaButton\n    Icon={CgDebug}\n    onClick={openDebugModal}\n    className=\"max-w-min\"\n  />\n</div>\n```\n\n调试输出会过滤掉 `content` 属性，仅显示配置结构：\n\n```tsx\nconst objCopy = { ...fileMap[selectedFileData] };\nobjCopy.content = \"File Content\";\nreturn JSON.stringify(objCopy, null, 2);\n```\n\n资料来源：[frontend/app/components/Ingestion/BasicSettingView.tsx:95-110]()\n\n## 系统信息展示\n\n### InfoView 组件\n\nInfoView 组件展示当前集成的系统信息，包括连接状态和版本信息：\n\n```tsx\n<div className=\"flex flex-col border-2 gap-2 border-bg-verba shadow-sm p-4 rounded-lg\">\n  <p className=\"text-sm lg:text-base font-semibold text-text-alt-verba\">\n    Connected to\n  </p>\n  <p className=\"text-text-verba\">{credentials.url}</p>\n</div>\n\n<div className=\"flex flex-col border-2 gap-2 border-bg-verba shadow-sm p-4 rounded-lg\">\n  <p className=\"text-sm lg:text-base font-semibold text-text-alt-verba\">\n    Deployment\n  </p>\n  <p className=\"text-text-verba\">{credentials.deployment}</p>\n</div>\n```\n\n资料来源：[frontend/app/components/Settings/InfoView.tsx:1-20]()\n\n### 版本信息\n\n系统显示 Weaviate 和 Verba 的版本信息，用于诊断集成问题：\n\n```tsx\n{nodePayload ? (\n  <p className=\"text-text-verba\">{nodePayload.weaviate_version}</p>\n) : (\n  <span className=\"loading loading-spinner loading-sm\"></span>\n)}\n```\n\n## 依赖管理\n\n### Python 依赖\n\nVerba 后端依赖以下核心包实现模型集成：\n\n| 包名 | 版本 | 用途 |\n|------|------|------|\n| `weaviate-client` | 4.9.6 | 向量数据库客户端 |\n| `fastapi` | 0.111.1 | API 服务框架 |\n| `uvicorn` | 0.29.0 | ASGI 服务器 |\n| `openai` | - | OpenAI API 接口 |\n\n资料来源：[setup.py:15-25]()\n\n## 版本更新记录\n\n| 版本 | 更新内容 |\n|------|----------|\n| 2.1.3 | 添加 OLLAMA_MODEL 和 OLLAMA_EMBED_MODEL 环境变量支持 |\n| 2.1.2 | 添加 Novita Generator，修复 spaCy 语言问题 |\n| 2.1.1 | 动态模型名称获取（基于 OpenAI URL 和 API Key） |\n| 2.1.0 | 添加 Upstage、Groq 支持，添加 AssemblyAI Reader |\n\n资料来源：[CHANGELOG.md:1-20]()\n\n## 最佳实践\n\n### 模型选择建议\n\n1. **嵌入模型选择**：根据向量数据库和语料特性选择合适的嵌入维度\n2. **生成模型选择**：考虑延迟、成本和能力平衡\n3. **检索器选择**：混合检索（Hybrid）通常效果最佳\n\n### 配置管理\n\n- 使用环境变量管理敏感凭证\n- 在非 Demo 模式下保存配置以实现持久化\n- 定期检查 CHANGELOG 获取最新支持的功能\n\n---\n\n<a id='page-deployment'></a>\n\n## 部署方式\n\n### 相关页面\n\n相关主题：[环境变量与配置](#page-configuration), [Verba 简介](#page-introduction)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [docker-compose.yml](https://github.com/weaviate/Verba/blob/main/docker-compose.yml)\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- [PYTHON_TUTORIAL.md](https://github.com/weaviate/Verba/blob/main/PYTHON_TUTORIAL.md)\n- [frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n</details>\n\n# 部署方式\n\nVerba（Golden Verba）是一款开源的 RAG（检索增强生成）应用，提供了多种部署方式以满足不同用户的需求。本页面详细介绍 Verba 的四种部署类型、配置方法以及各部署方式的技术细节。\n\n## 部署类型概述\n\nVerba 支持四种主要的部署类型，用户可以在首次启动时通过登录界面进行选择：\n\n| 部署类型 | 说明 | 使用场景 |\n|---------|------|---------|\n| Local | 使用 Weaviate Embedded，在应用内部初始化 Weaviate 实例 | 本地开发、快速原型 |\n| Docker | 在同一 Docker 网络中使用独立的 Weaviate 容器 | 容器化部署、生产环境 |\n| Weaviate Cloud (WCS) | 使用 Weaviate 云服务托管的实例 | 云端托管、无需自行维护 |\n| Custom | 用户自定义 Weaviate 实例 URL、端口和 API Key | 连接现有 Weaviate 基础设施 |\n\n资料来源：[frontend/app/components/Login/LoginView.tsx:55-58]()\n\n```mermaid\ngraph TD\n    A[Verba 部署选择] --> B[Local 部署]\n    A --> C[Docker 部署]\n    A --> D[Weaviate Cloud 部署]\n    A --> E[Custom 部署]\n    \n    B --> B1[Weaviate Embedded]\n    C --> C1[独立 Weaviate 容器]\n    D --> D1[Weaviate Cloud Services]\n    E --> E1[自建 Weaviate 实例]\n```\n\n## 前置要求\n\n### Python 环境要求\n\nVerba 对 Python 版本有明确要求：\n\n| 参数 | 要求 |\n|------|------|\n| Python 版本 | >= 3.10.0, < 3.13.0 |\n| 包管理工具 | pip |\n| 操作系统 | Windows、macOS、Linux |\n\n资料来源：[setup.py:9]()\n\n### 环境变量配置\n\nVerba 支持通过 `.env` 文件自动加载环境变量。建议在项目根目录创建 `.env` 文件，参考 `goldenverba/.env.example` 文件进行配置。\n\n| 环境变量 | 说明 |\n|---------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥 |\n| `COHERE_API_KEY` | Cohere API 密钥 |\n| `WEAVIATE_URL_VERBA` | Weaviate 服务地址 |\n| `OLLAMA_URL` | Ollama 服务地址 |\n| `OLLAMA_MODEL` | Ollama 生成模型 |\n| `OLLAMA_EMBED_MODEL` | Ollama 嵌入模型 |\n| `UNSTRUCTURED_API_KEY` | Unstructured API 密钥 |\n| `UNSTRUCTURED_API_URL` | Unstructured API 地址 |\n| `GITHUB_TOKEN` | GitHub 访问令牌 |\n| `DEFAULT_DEPLOYMENT` | 默认部署类型（Local/Docker/Weaviate/Custom）|\n\n资料来源：[README.md:28-35]()\n\n## 方式一：pip 安装部署\n\n这是最简单快捷的部署方式，适合快速体验 Verba。\n\n### 安装步骤\n\n```bash\n# 1. 创建虚拟环境\npython3 -m virtualenv venv\nsource venv/bin/activate  # Linux/macOS\n# venv\\Scripts\\activate.bat  # Windows\n\n# 2. 安装 Verba\npip install goldenverba\n\n# 3. 启动应用\nverba start\n\n# 4. 访问应用\n# 访问 http://localhost:8000\n```\n\n资料来源：[README.md:40-55]()\n\n### 指定端口和主机\n\n```bash\nverba start --port 8080 --host 0.0.0.0\n```\n\n### 包信息\n\n| 项目 | 值 |\n|------|-----|\n| 包名 | goldenverba |\n| 版本 | 2.1.3 |\n| 入口点 | `verba=goldenverba.server.cli:cli` |\n\n资料来源：[setup.py:1-12]()\n\n## 方式二：从源码构建\n\n适合需要自定义或参与开发的用户。\n\n### 安装步骤\n\n```bash\n# 1. 克隆仓库\ngit clone https://github.com/weaviate/Verba.git\n\n# 2. 创建并激活虚拟环境\npython3 -m virtualenv venv\nsource venv/bin/activate\n\n# 3. 安装（开发模式）\npip install -e .\n\n# 4. 启动\nverba start\n\n# 5. 访问\n# 访问 http://localhost:8000\n```\n\n资料来源：[README.md:87-105]()\n\n## 方式三：Docker 部署\n\nDocker 部署方式提供完整的容器化环境，包含 Verba 前端和 Weaviate 数据库。\n\n### 架构概览\n\n```mermaid\ngraph LR\n    A[用户浏览器] --> B[Verba Frontend<br/>:8000]\n    B --> C[Verba Backend]\n    C --> D[Weaviate<br/>:8080]\n    E[OLLAMA] --> C\n```\n\n### 快速启动\n\n```bash\n# 克隆仓库\ngit clone https://github.com/weaviate/Verba.git\n\n# 配置环境变量\n# 编辑 goldenverba/.env 文件\n\n# 启动容器\ndocker compose --env-file goldenverba/.env up -d --build\n```\n\n### Docker Compose 配置\n\nVerba 的 `docker-compose.yml` 定义了两个核心服务：\n\n| 服务 | 镜像/构建 | 端口 | 说明 |\n|------|----------|------|------|\n| verba | 本地构建 | 8000:8000 | Verba 应用前端和后端 |\n| weaviate | semitechnologies/weaviate:1.25.10 | 8080:8080 | 向量数据库 |\n\n资料来源：[docker-compose.yml:1-45]()\n\n### Verba 服务配置详情\n\n```yaml\nverba:\n  build:\n    context: ./\n    dockerfile: Dockerfile\n  ports:\n    - 8000:8000\n  environment:\n    - WEAVIATE_URL_VERBA=http://weaviate:8080\n    - OPENAI_API_KEY=$OPENAI_API_KEY\n    - COHERE_API_KEY=$COHERE_API_KEY\n    - OLLAMA_URL=http://host.docker.internal:11434\n    - OLLAMA_MODEL=$OLLAMA_MODEL\n    - OLLAMA_EMBED_MODEL=$OLLAMA_EMBED_MODEL\n  volumes:\n    - ./data:/data/\n  depends_on:\n    weaviate:\n      condition: service_healthy\n  healthcheck:\n    test: wget --no-verbose --tries=3 --spider http://localhost:8000\n    interval: 5s\n    timeout: 10s\n    retries: 5\n```\n\n资料来源：[docker-compose.yml:2-28]()\n\n### 健康检查配置\n\n| 参数 | 值 |\n|------|-----|\n| 测试命令 | wget --no-verbose --tries=3 --spider http://localhost:8000 |\n| 检查间隔 | 5秒 |\n| 超时时间 | 10秒 |\n| 重试次数 | 5次 |\n| 启动延迟 | 10秒 |\n\n资料来源：[docker-compose.yml:29-34]()\n\n### 访问地址\n\n| 服务 | 地址 |\n|------|------|\n| Verba 前端 | http://localhost:8000 |\n| Weaviate | http://localhost:8080 |\n\n## 虚拟环境配置\n\n### 创建虚拟环境\n\n推荐使用虚拟环境避免包冲突：\n\n```bash\n# 使用 virtualenv\npython3 -m virtualenv venv\n\n# 激活虚拟环境\n# Linux/macOS\nsource venv/bin/activate\n# Windows\nvenv\\Scripts\\activate.bat\n```\n\n资料来源：[PYTHON_TUTORIAL.md:1-25]()\n\n### 安装依赖\n\n激活虚拟环境后，使用以下命令安装 Verba：\n\n```bash\npip install goldenverba\n# 或从源码安装\npip install -e .\n```\n\n### 退出虚拟环境\n\n```bash\ndeactivate\n```\n\n## 环境变量配置详解\n\n### 必需的环境变量\n\n根据不同的功能模块，需要配置相应的 API 密钥：\n\n| 功能 | 环境变量 | 来源 |\n|------|---------|------|\n| OpenAI 生成/嵌入 | `OPENAI_API_KEY` | OpenAI 平台 |\n| Cohere 生成/嵌入 | `COHERE_API_KEY` | Cohere 平台 |\n| Ollama 本地模型 | `OLLAMA_URL`, `OLLAMA_MODEL`, `OLLAMA_EMBED_MODEL` | Ollama 部署 |\n| Unstructured 文档处理 | `UNSTRUCTURED_API_KEY`, `UNSTRUCTURED_API_URL` | Unstructured.io |\n| GitHub 数据源 | `GITHUB_TOKEN` | GitHub 设置 |\n\n资料来源：[docker-compose.yml:14-20]()\n\n### 配置优先级\n\n1. 启动时通过命令行参数传入\n2. `.env` 文件中的环境变量\n3. 应用内 UI 配置（首次登录后）\n\n## 部署方式对比\n\n| 特性 | pip 安装 | 源码构建 | Docker |\n|------|---------|---------|--------|\n| 安装难度 | ⭐ 简单 | ⭐⭐ 中等 | ⭐⭐ 中等 |\n| 启动速度 | 快 | 快 | 中等 |\n| 自定义能力 | 有限 | 完整 | 完整 |\n| 包含 Weaviate | 否（需额外配置） | 否（需额外配置） | 是 |\n| 适合场景 | 快速体验 | 开发调试 | 生产部署 |\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|---------|\n| Python 版本不兼容 | 确保使用 Python >= 3.10.0 且 < 3.13.0 |\n| 端口被占用 | 使用 `--port` 参数指定其他端口 |\n| 依赖安装失败 | 创建新的虚拟环境后重试 |\n| Docker 容器无法启动 | 检查 Docker daemon 是否运行，检查端口映射 |\n| Weaviate 连接失败 | 检查 `WEAVIATE_URL_VERBA` 环境变量配置 |\n\n### 验证安装\n\n安装完成后，可以通过以下方式验证：\n\n```bash\n# 检查 Verba 版本\nverba --version\n\n# 访问 Web 界面\n# 打开浏览器访问 http://localhost:8000\n```\n\n## 下一步\n\n部署完成后，建议进行以下操作：\n\n1. **配置 API 密钥**：在 `.env` 文件或应用 UI 中配置所需的 API 密钥\n2. **导入数据**：通过 \"Import Data\" 功能导入文档\n3. **配置 RAG 管道**：在 \"Config\" 页面配置生成模型和检索策略\n4. **开始对话**：在 \"Chat\" 页面开始与数据对话\n\n---\n\n<a id='page-configuration'></a>\n\n## 环境变量与配置\n\n### 相关页面\n\n相关主题：[部署方式](#page-deployment), [后端组件系统](#page-backend-components)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [goldenverba/.env.example](https://github.com/weaviate/Verba/blob/main/goldenverba/.env.example)\n- [frontend/app/types.ts](https://github.com/weaviate/Verba/blob/main/frontend/app/types.ts)\n- [frontend/app/components/Chat/ChatConfig.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Chat/ChatConfig.tsx)\n- [goldenverba/server/types.py](https://github.com/weaviate/Verba/blob/main/goldenverba/server/types.py)\n- [setup.py](https://github.com/weaviate/Verba/blob/main/setup.py)\n- [frontend/app/components/Login/LoginView.tsx](https://github.com/weaviate/Verba/blob/main/frontend/app/components/Login/LoginView.tsx)\n- [CHANGELOG.md](https://github.com/weaviate/Verba/blob/main/CHANGELOG.md)\n</details>\n\n# 环境变量与配置\n\nVerba（Golden RAGtriever）是一款开源的 RAG（检索增强生成）应用框架，支持多种部署方式和灵活的配置选项。本页面详细介绍 Verba 的环境变量配置、部署类型以及 RAG 管道配置。\n\n## 部署类型概述\n\nVerba 支持四种主要的部署类型，每种类型适用于不同的使用场景：\n\n```mermaid\ngraph TD\n    A[Verba 部署类型] --> B[Local 本地部署]\n    A --> C[Docker 容器部署]\n    A --> D[Weaviate 云服务]\n    A --> E[Custom 自定义部署]\n    \n    B --> B1[本地 Weaviate 实例]\n    C --> C1[Docker Compose 环境]\n    D --> D1[Weaviate Cloud Services]\n    E --> E1[自选 Weaviate 实例]\n```\n\n### 部署类型对比\n\n| 部署类型 | 适用场景 | 配置复杂度 | 资源配置 |\n|---------|---------|-----------|---------|\n| **Local** | 开发测试、个人使用 | 低 | 本地内存 |\n| **Docker** | 本地开发、多服务协作 | 中 | Docker 容器 |\n| **Weaviate** | 云端生产环境 | 低 | WCS 云服务 |\n| **Custom** | 企业自建、有特殊需求 | 高 | 自定义 URL/PORT/API Key |\n\n资料来源：[frontend/app/components/Login/LoginView.tsx:35-85]()\n\n## 环境变量配置\n\nVerba 通过环境变量控制应用的核心行为。以下是支持的环境变量及其功能：\n\n### 核心环境变量\n\n| 环境变量 | 类型 | 默认值 | 说明 |\n|---------|------|--------|------|\n| `DEFAULT_DEPLOYMENT` | string | 无 | 设置默认部署类型，可选值：`Local`、`Docker`、`Weaviate`、`Custom` |\n| `OLLAMA_MODEL` | string | 无 | Ollama 生成模型名称 |\n| `OLLAMA_EMBED_MODEL` | string | 无 | Ollama 嵌入模型名称 |\n\n资料来源：[CHANGELOG.md:12-14]()\n\n### 依赖包版本配置\n\nVerba 的核心依赖版本在 `setup.py` 中定义：\n\n| 依赖包 | 版本要求 | 用途 |\n|-------|---------|------|\n| `weaviate-client` | == 4.9.6 | Weaviate 客户端 |\n| `python-dotenv` | == 1.0.0 | 环境变量加载 |\n| `openpyxl` | == 3.1.5 | Excel 文件处理 |\n| `fastapi` | == 0.111.1 | API 服务框架 |\n| `uvicorn` | == 0.29.0 | ASGI 服务器 |\n| `gunicorn` | == 22.0.0 | WSGI 服务器 |\n| `click` | == 8.1.7 | CLI 工具 |\n| `wasabi` | == 1.1.2 | 日志工具 |\n\n资料来源：[setup.py:18-35]()\n\n## 前端配置系统\n\n### 配置类型定义\n\nVerba 前端使用 TypeScript 定义了完整的配置类型结构：\n\n```typescript\ninterface Credentials {\n  url: string;          // Weaviate 实例 URL\n  deployment: string;   // 部署类型\n  api_key?: string;     // API 密钥（可选）\n}\n```\n\n### 部署模式判断\n\n前端根据 `production` 环境变量决定显示的界面选项：\n\n```mermaid\ngraph TD\n    A[production 值] --> B[\"Demo\"]\n    A --> C[\"Local\"]\n    A --> D[\"Production\"]\n    \n    C --> C1[显示部署选择界面]\n    C1 --> C2[Weaviate 选项]\n    C1 --> C3[Docker 选项]\n    C1 --> C4[Custom 选项]\n    C1 --> C5[Local 选项]\n    \n    B --> B1[显示演示模式入口]\n    D --> D1[直接启动 Verba]\n```\n\n资料来源：[frontend/app/components/Login/LoginView.tsx:45-90]()\n\n### 导航菜单显示逻辑\n\n配置菜单的显示取决于当前部署模式：\n\n| 功能 | Demo 模式 | 其他模式 |\n|-----|----------|---------|\n| Chat 聊天 | ✅ 显示 | ✅ 显示 |\n| Documents 文档 | ✅ 显示 | ✅ 显示 |\n| Import Data 导入数据 | ❌ 隐藏 | ✅ 显示 |\n| Settings 设置 | ❌ 隐藏 | ✅ 显示 |\n\n资料来源：[frontend/app/components/Navigation/NavbarComponent.tsx:15-40]()\n\n## RAG 配置组件\n\n### ChatConfig 配置面板\n\nChatConfig 组件允许用户配置 RAG 管道的各个组件：\n\n```mermaid\ngraph LR\n    A[聊天配置面板] --> B[Reader 读取器]\n    A --> C[Embedder 嵌入器]\n    A --> D[Generator 生成器]\n    A --> E[Chunker 分块器]\n```\n\n### 配置重置与保存\n\n| 操作 | 函数 | 功能说明 |\n|-----|------|---------|\n| 重置配置 | `onResetConfig` | 恢复默认 RAG 配置 |\n| 保存配置 | `onSaveConfig` | 持久化当前配置 |\n| 获取状态 | `fetchingStatus` | 显示配置加载状态 |\n\n资料来源：[frontend/app/components/Chat/ChatConfig.tsx]()\n资料来源：[frontend/app/components/Chat/ChatInterface.tsx:25-45]()\n\n## 自定义部署配置\n\nCustom 部署类型允许用户指定完整的 Weaviate 连接参数：\n\n### 配置参数\n\n| 参数 | 必填 | 说明 |\n|-----|------|------|\n| Weaviate URL | 是 | Weaviate 实例的完整 URL 地址 |\n| Port | 是 | Weaviate 服务端口 |\n| API Key | 否 | 访问密钥（生产环境建议配置） |\n\n配置界面支持以下输入验证：\n- URL 格式验证\n- 端口范围检查（1-65535）\n- API Key 长度检查\n\n资料来源：[README.md:部署配置章节]()\n\n## 配置数据模型\n\n### 后端类型定义\n\nVerba 后端使用 Python 定义了配置相关的数据结构：\n\n```python\n# RAG 配置模型\nclass RAGConfig:\n    components: Dict[str, Component]\n    \n# 凭证模型  \nclass Credentials:\n    url: str\n    deployment: str\n    api_key: Optional[str]\n```\n\n### 前端类型映射\n\n| 后端类型 | 前端接口 | 用途 |\n|---------|---------|------|\n| `RAGConfig` | `RAGConfig` | RAG 组件配置 |\n| `Credentials` | `credentials` | 连接凭证 |\n| `Deployment` | `production` | 部署环境标识 |\n\n资料来源：[frontend/app/types.ts]()\n资料来源：[goldenverba/server/types.py]()\n\n## 环境配置工作流\n\n### 首次启动配置流程\n\n```mermaid\nsequenceDiagram\n    participant User as 用户\n    participant Frontend as 前端\n    participant Backend as 后端\n    \n    User->>Frontend: 选择部署类型\n    Frontend->>Backend: 发送连接请求\n    Backend->>Weaviate: 验证连接\n    Weaviate-->>Backend: 连接结果\n    Backend-->>Frontend: 返回凭证\n    Frontend->>User: 显示配置界面\n```\n\n### 生产环境配置\n\n对于生产环境部署，建议通过以下方式配置：\n\n1. **设置默认部署**：使用 `DEFAULT_DEPLOYMENT` 环境变量\n2. **配置 API 密钥**：在 Custom 部署模式下启用认证\n3. **配置 CORS**：允许指定的域名访问\n\n## 版本兼容性\n\nVerba 的 Python 版本要求与依赖兼容：\n\n| Python 版本 | 支持状态 | 说明 |\n|------------|---------|------|\n| 3.10 | ✅ 支持 | 最低要求 |\n| 3.11 | ✅ 支持 | 推荐版本 |\n| 3.12 | ✅ 支持 | 当前版本 |\n| 3.13 | ❌ 不支持 | 未测试 |\n\n资料来源：[setup.py:11]()\n\n## 最佳实践\n\n### 开发环境配置\n\n```bash\n# .env 文件示例\nDEFAULT_DEPLOYMENT=Local\nOLLAMA_MODEL=llama2\nOLLAMA_EMBED_MODEL=nomic-embed-text\n```\n\n### 生产环境配置\n\n```bash\n# 生产环境建议\nDEFAULT_DEPLOYMENT=Custom\nWEAVIATE_URL=https://your-instance.weaviate.cloud\nWEAVIATE_API_KEY=your-api-key\n```\n\n### 容器化部署\n\n使用 Docker 部署时，确保环境变量正确传递给容器：\n\n```bash\ndocker run -e DEFAULT_DEPLOYMENT=Docker \\\n           -e WEAVIATE_URL=http://weaviate:8080 \\\n           verba:latest\n```\n\n## 常见问题\n\n**Q: 如何跳过部署选择界面？**\n\nA: 设置 `DEFAULT_DEPLOYMENT` 环境变量为 `Local`、`Docker`、`Weaviate` 或 `Custom` 即可跳过选择步骤。\n\n**Q: Custom 部署需要哪些信息？**\n\nA: 需要提供 Weaviate 实例的 URL、端口和可选的 API 密钥。\n\n**Q: 支持哪些 Weaviate 客户端版本？**\n\nA: Verba 2.1.3 当前使用 `weaviate-client==4.9.6`。\n\n---\n\n*本文档基于 Verba v2.1.3 版本编写*\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> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 Verba 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Retrieval Augmented Generation (RAG) chatbot powered by Weaviate 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：Verba 简介。围绕“Verba 简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-features：核心功能特性。围绕“核心功能特性”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统整体架构。围绕“系统整体架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-frontend-structure：前端架构与组件。围绕“前端架构与组件”模拟一次用户任务，不展示安装或运行结果。\n5. page-backend-components：后端组件系统。围绕“后端组件系统”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“Verba 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-features\n输入：用户提供的“核心功能特性”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统整体架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-frontend-structure\n输入：用户提供的“前端架构与组件”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-backend-components\n输入：用户提供的“后端组件系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“Verba 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-features：Step 2 必须围绕“核心功能特性”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统整体架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-frontend-structure：Step 4 必须围绕“前端架构与组件”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-backend-components：Step 5 必须围绕“后端组件系统”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/weaviate/Verba\n- https://github.com/weaviate/Verba#readme\n- README.md\n- CHANGELOG.md\n- TECHNICAL.md\n- goldenverba/components/embedding/__init__.py\n- goldenverba/components/generation/__init__.py\n- goldenverba/components/chunking/__init__.py\n- goldenverba/server/api.py\n- goldenverba/verba_manager.py\n- goldenverba/components/interfaces.py\n- frontend/app/page.tsx\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 Verba 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n  2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\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"
}
