Oliva：语音控制的多智能体产品搜索助手

综合介绍

Oliva 是一个开源的多智能体助手工具，由 Deluxer 在 GitHub 上开发。它通过多个 AI 智能体协作，帮助用户在 Qdrant 数据库中搜索产品信息。主要特点是支持语音操作，结合 LangChain 和 Superlinked 技术，提供高效的语义搜索功能。Oliva 适合开发者或研究者使用，代码完全开放，用户可以下载、修改和部署。它不仅是一个实用工具，也是一个学习多智能体架构的平台。项目依赖现代技术栈，如 Livekit 和 Deepgram，支持实时语音交互。

功能列表

• 语音控制搜索：用户通过语音输入指令，智能体完成搜索任务。
• 多智能体协作：多个 AI 智能体分工处理任务，由监督者智能体协调。
• 语义搜索支持：基于 LangChain 和 Superlinked，实现精准内容检索。
• 开源代码：提供完整代码，用户可自由修改和扩展功能。
• 本地或云端部署：支持在本地或服务器上运行，灵活性高。

使用帮助

Oliva 是一个基于 GitHub 的开源项目，使用前需要配置环境和依赖。以下是详细的安装和使用指南，帮助你快速上手。

安装流程

1. 准备 Python 环境
   Oliva 需要 Python 3.12 或更高版本。检查版本：

python --version

如果版本不够，去 Python 官网 下载安装。

2. 克隆项目
   打开 https://github.com/Deluxer/oliva，点击 "Code" 按钮，复制 HTTPS 链接，然后运行：

git clone https://github.com/Deluxer/oliva.git

需要先安装 Git，下载地址：Git 官网。

3. 进入项目目录
   下载后进入文件夹：

cd oliva

4. 创建虚拟环境
   为避免依赖冲突，建议创建虚拟环境：

python -m venv .venv

激活环境：

• Windows：
  复制复制复制复制复制复制复制复制复制复制复制复制复制

  复制

  .venv\Scripts\activate

• Mac/Linux：
  复制复制复制复制复制复制复制复制复制复制复制复制

  复制

  source .venv/bin/activate

5. 安装依赖
   使用 uv 工具同步依赖：

uv sync

这会自动创建虚拟环境并安装所有依赖，如 LangChain、Superlinked 等。如果没有 uv，先安装：

pip install uv

6. 配置 Qdrant 数据库
   使用 Docker 运行 Qdrant：

docker run -p 6333:6333 -p 6334:6334 -e QDRANT__SERVICE__API_KEY=your_api_key -v "$(pwd)/qdrant_storage:/qdrant/storage:z" qdrant/qdrant

需要先安装 Docker，下载地址：Docker 官网。将 your_api_key 替换为自定义密钥。

7. 设置 Livekit 账户
   在 Livekit Cloud 注册，获取以下信息：

LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_key
LIVEKIT_API_SECRET=your_secret

将这些值保存到环境变量中。

8. 配置环境变量
   复制示例文件并编辑：

cp .env.example .env

在 .env 文件中填入 Livekit 和 Deepgram 的密钥（Deepgram 需在 Deepgram 官网 注册获取）。

9. 填充数据库
   按照 tabular-semantic-search-tutorial 的说明设置数据，或直接解压 assets/snapshot.zip 中的快照到 Qdrant。

主要功能操作

• 启动语音助手
  在项目目录下运行：

make oliva-start

这会启动语音助手服务。确保 Qdrant 和 Livekit 已运行。

• 连接前端界面
  访问 Agent Playground，输入你的 Livekit 项目凭证连接助手。或本地运行：
• 克隆 Agent Playground 仓库：
  复制复制复制复制复制

  复制

  git clone https://github.com/livekit/agents-playground.git

• 安装依赖并启动：
  复制复制复制复制

  复制

  npm install
  npm run start

在界面中输入语音指令，例如“搜索某产品”。

• 语义搜索
  有两种搜索方式：
• 使用 Superlinked：
  复制复制复制

  复制

  make agent-search-by-superlinked

• 使用 JSON 文件：
  复制复制

  复制

  make agent-search-by-json

搜索结果由智能体从 Qdrant 数据库返回。

特色功能操作

• 语音交互
  Oliva 支持通过语音输入指令。启动后，在 Agent Playground 中点击麦克风图标，说出需求（如“找一款手机”），Deepgram 会将语音转为文本，智能体处理后返回结果。监督者智能体会决定哪个智能体执行任务。
• 多智能体协作
  项目采用图状工作流（LangGraph），包含多个节点（如搜索、生成）和条件边。配置文件在 app/agents/langchain/config/ 中，可调整智能体行为。核心逻辑在 app/agents/ 目录下。
• 自定义扩展
  想增加功能？编辑 app/agents/implementations/ 中的智能体代码。例如，添加新工具需在 app/agents/langchain/tools/ 中定义。

注意事项

• 确保网络畅通，Livekit 和 Deepgram 需要联网。
• 项目依赖较多，初次配置可能需多次调试。
• 检查 GitHub 提交，确保使用最新代码。

通过以上步骤，你可以完整运行 Oliva 并体验语音控制的搜索功能。

应用场景

1. 产品信息查询
   用户通过语音询问产品详情，Oliva 从 Qdrant 数据库返回结果，适合电商场景。
2. 技术学习
   开发者研究多智能体架构，修改代码测试不同工作流。
3. 实时演示
   在会议中展示语音助手功能，突出 AI 协作能力。

QA

1. 语音助手不响应怎么办？
   检查 Livekit 和 Deepgram 的密钥是否正确配置，确保网络连接正常。
2. Qdrant 启动失败怎么办？
   确认 Docker 已运行，端口 6333 和 6334 未被占用。
3. 可以离线使用吗？
   语音功能需联网，搜索功能若数据本地化可离线运行。