Project Pastra本地开发环境搭建指南

项目概述

Project Pastra是一个基于Python开发的智能对话系统，集成了Google Gemini AI模型和多种实用工具（如天气查询、日历管理等）。本文将详细介绍如何在本地环境中搭建和运行该项目，适合开发者进行二次开发或功能测试。

环境准备

在开始搭建前，请确保您的系统满足以下要求：

1. Python环境

   • Python 3.8或更高版本
   • pip包管理工具（通常随Python一起安装）

2. API密钥

   • Google Gemini API密钥（核心功能必需）
   • OpenWeather API密钥（仅当需要使用天气工具时）

3. 可选组件

   • Google Cloud Functions（用于工具集成）
   • Google Cloud SDK（如需使用Secret Manager）

详细搭建步骤

1. 获取项目代码

首先需要获取项目源代码到本地开发环境：

git clone <项目仓库地址>
cd project-pastra

2. 后端配置

后端服务是项目的核心，负责处理AI对话和工具集成：

1. 进入server目录：

   cd server
   

2. 创建并配置环境变量文件：

   cp .env.example .env
   nano .env
   

   关键配置项说明：

   • GOOGLE_API_KEY: Gemini API密钥
   • WEATHER_FUNCTION_URL: 天气功能云函数地址
   • CALENDAR_FUNCTION_URL: 日历功能云函数地址
   • OPENWEATHER_API_KEY: OpenWeather API密钥

3. 安装Python依赖：

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

3. 启动后端服务

python server.py

服务默认监听8081端口，保持此终端窗口运行。

4. 前端服务配置

1. 新建终端窗口，进入client目录：

   cd ../client
   

2. 启动Python HTTP服务器：

   python -m http.server 8000
   

5. 访问应用

在浏览器中访问：

• 开发界面：http://localhost:8000/index.html
• 移动端界面：http://localhost:8000/mobile.html

功能验证

启动后，建议进行以下测试：

1. 检查浏览器控制台是否有WebSocket连接错误
2. 测试语音输入和文本输入功能
3. 观察后端日志中的处理信息

常见问题解决

连接问题

• WebSocket连接失败：确认后端服务是否正常运行，检查端口配置
• API认证错误：验证.env文件中的API密钥是否正确

功能异常

• 天气/日历工具不可用：检查云函数URL配置和网络连接
• 语音输入无效：确保浏览器已授予麦克风权限

环境问题

• Python依赖缺失：确认已激活虚拟环境并安装所有依赖
• 端口冲突：修改server.py或HTTP服务器的监听端口

高级配置建议

对于需要深度定制的开发者，可以考虑：

1. 使用Vertex AI端点替代默认API
2. 通过Google Cloud Secret Manager管理敏感信息
3. 自定义工具集成，扩展项目功能

结语

通过本文的指导，您应该已经成功在本地搭建了Project Pastra的开发环境。这个项目为开发者提供了一个强大的基础框架，可以在此基础上进行各种AI对话应用的开发和探索。建议初次接触的开发者先从基本功能开始熟悉，逐步深入了解其架构和扩展机制。