Google Home API Agent

谷歌家庭API代理

一个基于RAG（检索增强生成）技术的代理，用于查询Google Home Android API文档。

概述

这个项目提供了一个智能代理，可以通过以下方式回答有关Google Home Android API的问题：

• 从developers.home.google.com爬取官方文档
• 将文档处理并划分为语义部分
• 构建混合搜索索引（向量嵌入 + BM25）
• 利用大型语言模型（LLMs）提供准确且上下文感知的答案
• 新具有上下文感知输出模式（问题导向与集成导向）的MCP服务器

项目结构

google-home-api-agent/
├── data/
│   └── home-api/
│       └── android/
│           ├── *.md                    # Raw crawled markdown files
│           ├── processed/              # Processed chunks and metadata
│           │   ├── chunks.jsonl
│           │   ├── code_examples.jsonl
│           │   └── metadata.json
│           └── index/                  # Search indices
│               ├── chroma/             # Vector embeddings
│               ├── bm25_index.pkl      # Keyword search index
│               └── chunk_mapping.json  # Chunk ID mappings
├── scripts/
│   ├── google-home-android-api.py     # Documentation crawler
│   ├── process_docs.py                # Document processor
│   └── build_index.py                 # Index builder
├── google_home_rag/
│   ├── __init__.py
│   ├── agent.py                       # RAG agent implementation
│   └── retriever.py                   # Hybrid retriever
├── tests/
│   └── rag_tests/
│       ├── evaluation_framework.py    # Evaluation tools
│       ├── run_evaluation.py          # Test runner
│       └── profile_performance.py     # Performance profiling
├── google_home_mcp_server.py          # MCP server implementation
├── run_mcp_server.py                  # MCP server startup script
├── MCP_SERVER.md                      # MCP server documentation
├── pyproject.toml
├── .env.example
└── README.md

设置

1. 先决条件

• Python 3.10 或更高版本
• 紫外线 （推荐）或使用 pip

2. 安装

使用紫外线（推荐）：

cd /Users/tim/PycharmProjects/google-home-api-agent

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

使用 pip：

cd /Users/tim/PycharmProjects/google-home-api-agent

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

3. 配置

复制示例环境文件并添加您的API密钥：

cp .env.example .env

编辑 .env 并添加您的OpenAI API密钥：

OPENAI_API_KEY=your-actual-api-key-here

使用

MCP 服务器（推荐用于AI助手）

新使用MCP服务器，实现与Claude Desktop、Cline及其他MCP客户端的无缝集成：

# Start the MCP server
python run_mcp_server.py

MCP服务器提供：

• ask_question - 获取无需导入的简洁代码片段（用于学习）
• get_code_integration - 获取包含导入语句的完整代码（用于实现）
• search_documentation - 浏览文档部分

📖 书本 完整的MCP服务器文档

爬取文档

更新或重新抓取文档：

python scripts/google-home-android-api.py

这将会：

• 从 developers.home.google.com 爬取所有已配置的页面
• 将Markdown文件保存到 data/home-api/android/

处理文件

将原始的Markdown内容处理成结构化的部分：

python scripts/process_docs.py

这将会：

• 解析Markdown文件
• 提取代码块和元数据
• 按部分划分文档块
• 将处理后的数据保存到 data/home-api/android/processed/

构建索引

构建混合搜索索引：

python scripts/build_index.py

这将：

• 使用ChromaDB创建向量嵌入
• 构建BM25关键词索引
• 保存索引到 data/home-api/android/index/

使用RAG代理

from pathlib import Path
from google_home_rag import RAGAgent

# Initialize the agent
index_dir = Path("data/home-api/android/index")
agent = RAGAgent(index_dir=index_dir, model="gpt-4o-mini")

# Ask a question
question = "How do I commission a device using the Android API?"
answer = agent.answer(question, top_k=5)

print(answer)

进行评估

评估RAG系统性能：

cd tests/rag_tests
python run_evaluation.py

性能分析

为RAG系统进行性能分析：

cd tests/rag_tests
python profile_performance.py

文档覆盖率

该代理目前涵盖：

开始使用

• SDK设置和OAuth
• 初始化和权限设置

API指南

• 概述与数据模型
• 连接性和互操作性
• 错误处理

调试API

• 设备调试
• 多管理员支持

结构API

• 家庭结构管理

设备API

• 设备控制与监控
• 支持的设备类型和特性
• 特定于制造商的特性

自动化API

• 自动化设计与构建
• DSL（领域特定语言）

- 基本模式 - 复杂的图案 - 常备首发（或常用启动者）

• 支持的特性与简化特性
• 被阻止的操作
• 发现与实例

测试

• 测试指南

发展

添加新的文档页面

编辑 scripts/google-home-android-api.py 并在其中添加URL PAGES_TO_CRAWL 列表：

PAGES_TO_CRAWL = [
    "/apis/android/your-new-page",
    # ...
]

然后重新运行爬虫、处理器和索引构建器。

定制RAG代理

RAG代理可以根据需求进行定制 google_home_rag/agent.py：

• 调整检索参数（top_k，重排序）
• 修改提示模板
• 更换LLM模型
• 添加自定义过滤器

测试

添加测试用例到 tests/rag_tests/test_cases/：

[
  {
    "question": "Your question here",
    "expected_keywords": ["keyword1", "keyword2"],
    "category": "category_name"
  }
]

依赖项

核心依赖项：

• “crawl4ai”可以翻译为“用于AI的爬虫”或“AI爬虫工具”。这里，“crawl”指的是网络爬虫（即自动浏览网页并收集信息的程序），“4ai”则表明了这个爬虫是专为人工智能（AI）设计或用于人工智能相关的任务网页抓取和内容提取
• ChromaDB用于嵌入的向量数据库
• sentence-transformers（句子转换模型库）嵌入生成
• rank-bm25（这个短语在中文中没有直接对应的翻译，但可以解释为）：基于BM25的排名基于关键词的搜索
• OpenAI大语言模型（LLM）接口
• litellm（该词本身无直接中文对应，可理解为一个特定技术或项目的名称，如“小llm”或保持原样，具体含义需根据上下文确定）多供应商大型语言模型支持

故障排除

ChromaDB 问题

如果你遇到ChromaDB错误：

# Clear the index and rebuild
rm -rf data/home-api/android/index/chroma
python scripts/build_index.py

导入错误

确保项目以可编辑模式安装：

uv pip install -e .
# or
pip install -e .

API密钥问题

验证您的 .env 文件位于项目根目录，包含：

OPENAI_API_KEY=sk-...

许可证

这个项目是用于教育和研究目的。请参阅谷歌的服务条款以获取其API文档。

做出贡献

欢迎投稿！请：

1. 为仓库创建分支（或：克隆仓库）
2. 创建一个特性分支
3. 做出你的更改
4. 提交拉取请求

支持

如需报告问题或提出疑问，请在项目仓库中提交一个问题。