适用场景：

• 生产环境部署
• 完整的容器化服务
• 需要 Weaviate 数据库的完整环境
• 团队协作时的环境一致性

功能：

• 自动安装和配置 UV
• 同步项目依赖
• 启动完整的 Docker Compose 服务栈
• 包含 Weaviate 数据库、初始化脚本和 Verba 应用

使用方法：

chmod +x start-docker.sh
./start-docker.sh

启动的服务：

• Verba 应用: http://localhost:8000
• Weaviate 数据库: http://localhost:8080
• Weaviate 控制台: http://localhost:3000

# 确保有必要的配置文件
- pyproject.toml  # UV 依赖配置
- docker-compose.yml  # Docker 服务配置
- .env  # 环境变量 (或设置环境变量)

创建 .env 文件：

OPENAI_API_KEY=your_openai_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
COHERE_API_KEY=your_cohere_key_here
# ... 其他必要的API密钥

# 如果 Docker 方式有问题，可以分步执行：
docker compose down -v  # 清理环境
docker compose up weaviate -d  # 先启动数据库
./start-local.sh  # 然后本地启动应用

访问 Verba 应用: http://localhost:8000，进入操作界面。

在 Chat 界面中，点击 Config 进行以下配置：

• Embedder（嵌入模型）：选择合适的嵌入模型（如 text-embedding-3-large）
• Generator（生成模型）：选择对话生成模型（如 gpt-4 或 gpt-3.5-turbo）

💡 提示：Embedder 模型的选择会影响后续所有步骤，请谨慎选择。

1. 进入 Import Data 界面
2. 上传你的原始文件（支持 PDF、DOCX、TXT 等格式）
3. 点击页面左侧右下角的 Import 按钮
4. 系统会自动将原始文件进行 Chunking（分块处理） 并转换为 Documents

📁 说明：Chunking 是将大文档拆分成小块的过程，便于后续的语义搜索和检索。

1. 进入 Documents 界面
2. 查看和管理已导入的文档
3. 选择性导入对话：勾选你希望在对话中使用的文档
   • 被选中的文档将在对话时作为知识库被检索
   • 未选中的文档仅存储在系统中，不参与对话

第一步中选择的 Embedder 模型必须与对话时使用的模型保持一致！

正确示例：

• 配置时使用：text-embedding-3-large
• 对话时使用：text-embedding-3-large ✅

错误示例：

• 配置时使用：text-embedding-3-large
• 对话时使用：text-embedding-3-small ❌

🚨 原因：不同的嵌入模型生成的向量维度和语义表示不同，混用会导致检索结果不准确或系统报错。

graph TD
    A[开始] --> B[第一步：配置 Embedder 和 Generator]
    B --> C[第二步：导入原始文件]
    C --> D[系统自动 Chunking 处理]
    D --> E[第三步：在 Documents 界面管理文档]
    E --> F[选择参与对话的文档]
    F --> G[开始对话]
    G --> H{Embedder 模型是否一致？}
    H -->|是| I[正常对话 ✅]
    H -->|否| J[检索错误 ❌]
    J --> B

Q: 为什么要进行 Chunking？ A: 大文档需要分割成小块，便于：

• 提高检索精度
• 减少上下文长度
• 优化响应速度

Q: 如何判断选择了正确的 Embedder 模型？ A: 在 Chat 界面的 Config 中确认，确保导入数据时和对话时使用相同的模型。

Q: 可以同时使用多个 Embedder 模型吗？ A: 不建议。每个文档集合应使用统一的 Embedder 模型以确保检索一致性。