AI Hackathon Demo

美国国家航空航天局文件问答系统

由LangChain和OpenAI支持的智能问答系统，提供来自NASA技术文档的高管级见解。

    ](https://docker.com)

📋 目录

• 概述
• 特性
• 先决条件
• 安装
• 配置
• 用法

- 快速开始 - 示例提示 - 高级用法

• 建筑
• 调试与故障排除
• 发展
• 贡献
• 许可证

🎯 概述

该系统将美国国家航空航天局的技术文档转化为专为高管和技术领导者设计的交互式问答界面。它采用LangChain的React代理模式和OpenAI的GPT-5-mini构建，通过从处理过的NASA文档中智能检索相关信息，提供准确的上下文答案。该系统具有可选的MCP（模型上下文协议）集成功能，可增强文件系统功能，并遵循干净的5层模块化架构。

这解决了什么问题？

• 信息过载：美国国家航空航天局的文件既广泛又复杂，该系统可以快速提取关键见解
• 行政决策：提供技术文件的执行级摘要和分析
• 合规性跟踪：允许快速检索治理和合规信息
• 知识发现：揭示美国国家航空航天局不同文件和倡议之间的联系

为什么是这种技术栈？

• LangChain：提供强大的文档处理、检索管道和React代理框架
• OpenAI GPT-5-mini：提供高质量、经济高效的文本生成和嵌入
• 色度矢量数据库：启用跨文档块的语义搜索
• MCP（模型上下文协议）：文件系统和外部工具访问的可选集成
• 反应代理模式：复杂查询的智能推理和工具选择

✨ 特性

• 📄 PDF文档处理：自动接收和处理NASA PDF
• 🔍 语义搜索：基于向量的相关内容相似性搜索
• 🎯 摘要报告：为高管受众量身定制的回应
• ⚡ 快速检索：对361个索引文档进行亚秒级查询处理
• 🛠️ 综合调试：用于系统健康监测的内置工具
• 🔧 模块化架构：具有单一责任组件的干净5层架构
• 🔌 MCP集成：文件系统操作的可选模型上下文协议支持
• 🤖 反应代理模式：智能工具选择和推理能力
• 🐳 Docker就绪：具有交互式支持的容器化部署
• 📊 分析就绪：内置指标和性能监控
• ⚙️ 环境驱动：具有验证和优雅降级功能的配置管理

🔧 先决条件

系统要求

• python：3.13+（用3.13.1测试）
• OpenAI API密钥：嵌入和文本生成所需
• 记忆：建议矢量操作使用4GB+RAM
• 存储：矢量数据库和文件500MB+

支持的平台

• macOS（ARM64/Intel）
• Linux（x86_64/ARM64）
• Windows（WSL推荐）

🚀 安装

您可以使用Python或Docker在本地运行NASA问答系统。选择最适合您环境的方法：

• 🐍 本地Python设置：具有调试工具的完整开发功能
• 🐳 Docker设置：隔离的环境，一致的部署（参见 )

💡 专业提示：从获取OpenAI API密钥 platform.openai.com/account/api-keys

快速设置（推荐）

# 1. Clone and navigate to the project
git clone https://github.com/driches/ai-hackathon-demo
cd hackathon-demo

# 2. Edit your API key in the .env file
# Replace 'your_openai_api_key_here' with your actual OpenAI API key
cp .env.example .env
nano .env  # or use your preferred editor

# 3. Build Docker Container
make docker-build

# 4. Start Chat
make docker-interactive

本地设置

# 1. Run the automated setup script
make setup

# 2. Edit your API key in the .env file
# Replace 'your_openai_api_key_here' with your actual OpenAI API key
cp .env.example .env
nano .env  # or use your preferred editor

激活发展

# Activate the environment for future sessions
source ./activate.sh

# Or use the standard activation
source .venv/bin/activate

2.验证设置

# Test your configuration
make debug-env

# Expected output:
# ✅ OPENAI_API_KEY: Set
# ✅ Python 3.13.1 detected
# ✅ Virtual environment active

🎮 用法

快速开始

1.完成设置

# Activate environment, download data, and ingest documents
source ./activate.sh
make fetch-data
make ingest

# Verify the vector database
make debug-vectordb

# Start an MCP server
make mcp-http 

2.开始提问

# To run with MCP tools (if configured in .env)
make run

# To run without MCP tools
make run-no-mcp

# You'll see the prompt:
# Ask ▶ 

3.尝试第一个查询

Ask ▶ What are the key risk mitigation strategies in NASA's Systems Engineering Handbook?

→ The NASA Systems Engineering Handbook outlines several key risk mitigation strategies:

1. **Risk-Informed Decision Making (RIDM)**: A systematic approach that combines...
2. **Continuous Risk Management (CRM)**: Ongoing identification and assessment...
3. **Technical Risk Assessment**: Dual approach combining quantitative and qualitative...

[Detailed response continues...]

4.退出应用程序

Ask ▶ quit
# or press Ctrl+C

示例提示

以下是经过验证的提示，展示了系统的功能：

高级用法

自定义文档处理

要添加自己的PDF文档：

# 1. Add PDFs to the data directory
cp your-document.pdf ./data/

# 2. Re-ingest documents
make clean-vectordb
make ingest

# 3. Verify new documents
make debug-vectordb

批量查询处理

# Test multiple queries
make test-retrieval

# Custom retrieval testing
python test_retrieval.py

性能监控

# Comprehensive system check
make debug

# Individual component testing
make test-components
make debug-embeddings

MCP（模型上下文协议）集成

该系统支持可选的MCP集成，以增强文件系统操作和NASA文档搜索。

什么是MCP？

MCP（模型上下文协议）是一种允许AI代理与外部工具和服务交互的协议。在我们的系统中，它提供了补充NASA文档搜索的文件系统访问功能。

MCP功能

• 文件系统操作：读取、写入、列出文件和目录
• 分布式体系结构：MCP服务器与主应用程序分开运行
• 故障弱化：系统可以在有或没有MCP服务器的情况下工作
• 异步/同步桥：MCP的异步协议和LangChain的同步工具之间的无缝集成

使用MCP运行

# 1. Configure MCP in your .env file
# This is usually done once
echo "MCP_SERVER_URLS=http://127.0.0.1:8000/mcp/" >> .env

# 2. Start an MCP server
make mcp-http 

# 3. Run the application with MCP support
make run

# The agent will now have both NASA search AND filesystem tools

无MCP运行

# Run with NASA documents only (no filesystem tools)
make run-no-mcp

# Or leave MCP_SERVER_URLS empty in .env file

MCP架构

User Query → React Agent → Tool Selection
                 │
       ┌─────────┼─────────┐
       │         │         │
  NASA Search   MCP    File System
  (Vector DB)  Bridge   Operations
       │         │         │
  Executive    HTTP     Read/Write
  Response    Request    Files

🐳 Docker部署

Docker为运行NASA问答系统提供了一个隔离的、可重复的环境。容器化版本自动处理数据获取、文档摄取和应用程序启动。

Docker的先决条件

• Docker 桌面版：推荐最新版本
• OpenAI API密钥：必填，已在中配置 .env 文件
• 记忆：4GB+RAM用于Docker容器操作

快速启动Docker

1.构建Docker镜像

# Build the Docker image with all dependencies
make docker-build

# Or use direct Docker command:
# docker build -t nasa-qa-demo .

2.互动跑步（推荐）

# Start interactive Q&A session in Docker
make docker-interactive

# This will:
# ✅ Download NASA documents automatically
# ✅ Process them into vector database
# ✅ Start the interactive Q&A interface
# ✅ Show the thinking animation
# ✅ Allow you to ask questions and get responses

您将看到如下输出：

🐳 Starting interactive NASA Q&A system in Docker...
💡 You can now ask questions about NASA documents!
💡 Type 'quit', 'exit', or 'q' to stop, or press Ctrl+C

↓ nasa_se_handbook.pdf
↓ artemis_i_press_kit.pdf
↓ clps_press_kit.pdf
NASA docs ready → ./data
🚀 NASA Document Q&A System
Ask questions about NASA documents. Type 'quit', 'exit', or 'q' to stop.
============================================================
Ask ▶ 

3.测试你的Docker设置

# Run non-interactive mode for testing
make docker-run

# This validates the complete pipeline without user interaction

Docker命令参考

直接Docker命令

如果你更喜欢直接使用Docker：

# Build image
docker build -t nasa-qa-demo .

# Run interactively (recommended for Q&A)
docker run -it --rm --env-file .env nasa-qa-demo

# Run non-interactively (for testing)
docker run --rm --env-file .env nasa-qa-demo

Docker与本地开发

Docker故障排除

常见Docker问题

1.集装箱立即出口

# Check Docker logs
docker logs 

# Verify .env file exists and has OPENAI_API_KEY
ls -la .env

2.交互模式不起作用

# Use our recommended command
make docker-interactive

# NOT: docker-compose up (has interactive input limitations)

3.Docker中的API关键问题

# Verify .env file format
cat .env

# Should contain:
# OPENAI_API_KEY=sk-your-actual-key-here

4.内存不足错误

# Increase Docker memory limit in Docker Desktop
# Recommended: 4GB+ for smooth operation

何时使用Docker

✅ 在以下情况下使用Docker：

• 部署到生产服务器
• 确保跨团队的环境一致
• 在CI/CD管道中运行
• 避免本地Python环境冲突
• 向利益相关者展示

🔧 在以下情况下使用本地开发：

• 积极开发和调试代码
• 需要访问调试工具(make debug)
• 频繁的代码更改和测试
• 需要全面的性能优化

🏗️ 建筑

系统流程

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│  PDF Docs   │───▶│   Ingestion  │───▶│  Vector DB  │
└─────────────┘    └──────────────┘    └─────────────┘
                                              │
┌─────────────┐    ┌──────────────┐    ┌─────▼─────┐
│   Response  │◀───│  AI Agent    │◀───│ Retrieval │
└─────────────┘    └──────────────┘    └───────────┘
                           ▲                  ▲
                    ┌──────▼──────┐    ┌──────▼──────┐
                    │ User Query  │    │ MCP Tools   │
                    └─────────────┘    └─────────────┘

5层清洁架构

该系统遵循模块化、干净的架构模式，具有不同的层：

1. 配置层 (common/config.py)：环境设置和验证
2. 数据层 (common/nasa_search.py)：矢量数据库和文档检索
3. 集成层 (common/mcp_client.py)：外部MCP服务器连接
4. 代理层 (common/agent_factory.py)：AI代理创建和配置
5. 表示层 (main.py)：用户界面和交互

关键组件

• main.py：使用模块化组件的主要应用程序
• common/config.py：环境和配置管理及验证
• common/nasa_search.py：NASA文件搜索的RAG实施
• common/mcp_client.py：MCP（模型上下文协议）与异步/同步桥的集成
• common/agent_factory.py：用于创建配置的AI代理的工厂
• common/thinking_spinner.py：支持线程的UI组件
• ingest.py：PDF处理和矢量数据库创建
• debug_embeddings.py：全面的预埋管道测试
• test_retrieval.py：查询测试和验证
• chroma_db/：矢量数据库存储
• data/：源PDF文档

代理架构（反应模式）

┌─────────────┐
│ User Query  │
└─────┬───────┘
      │
┌─────▼───────┐
│ React Agent │ ◀── LangChain create_react_agent
└─────┬───────┘
      │
┌─────▼───────┐    ┌─────────────┐    ┌─────────────┐
│    Tools    │◀──▶│ NASA Search │ +  │ MCP Tools   │
└─────┬───────┘    └─────────────┘    └─────────────┘
      │                    │                  │
┌─────▼───────┐    ┌─────▼─────┐    ┌─────▼─────┐
│  Response   │    │Vector DB  │    │File System│
└─────────────┘    └───────────┘    └───────────┘

使用的设计模式

• 单例模式：配置和客户端实例
• 工厂模式：使用不同的工具配置创建代理
• 适配器模式：用于MCP集成的异步/同步桥
• 策略模式：基于MCP服务器可用性的不同工具集
• 模板方法：标准化的代理创建工作流程
• 命令模式：通过代理调用处理的用户查询

🔍 调试与故障排除

内置调试工具

该系统包括可通过以下方式访问的全面调试命令 make:

# Complete system health check
make debug

# Individual component testing
make debug-env          # Environment and configuration
make debug-embeddings   # OpenAI embeddings pipeline
make debug-vectordb     # Vector database inspection
make debug-graph        # LangGraph workflow visualization
make test-components    # LLM and embedding connectivity
make test-retrieval     # Query processing validation

常见问题及解决方法

1.OpenAI API关键问题

问题: AuthenticationError: Error code: 401

解决方案:

# Check API key format
make debug-env

# Verify key starts with 'sk-'
echo $OPENAI_API_KEY

# Force reload environment
unset OPENAI_API_KEY
source .venv/bin/activate

2.空矢量数据库

问题：未检索到用于查询的文档

解决方案:

# Check database status
make debug-vectordb

# Re-ingest documents if needed
make clean-vectordb
make ingest

3.查询性能缓慢

问题：查询时间>10秒

解决方案:

# Test embedding performance
make debug-embeddings

# Check system resources
htop  # or Activity Monitor on macOS

4.导入/模块错误

问题: ModuleNotFoundError 或 ImportError

解决方案:

# Quick fix: Re-run setup
./setup.sh

# Or verify virtual environment manually
make debug-env

# Reinstall dependencies if needed
pip install -r requirements.txt

# Check Python version compatibility
python --version  # Should be 3.13+

5.环境问题

问题：虚拟环境或激活问题

解决方案:

# Use the activation script
source ./activate.sh

# Or re-run complete setup
./setup.sh

# Verify environment status
make debug-env

性能基准

• 查询响应时间：典型值\<5秒
• 文件摄入：3个大PDF约2分钟
• 向量搜索：对于361个文档，小于1秒
• 内存使用：运行时约500MB

调试命令参考

🛠️ 发展

项目结构

.
├── main.py                # Main application
├── ingest.py              # Document processing
├── fetch_nasa_data.py     # NASA document downloader  
├── debug_embeddings.py    # Embedding diagnostics
├── test_retrieval.py      # Query testing
├── requirements.txt       # Python dependencies
├── Makefile              # Automation commands (includes Docker targets)
├── Dockerfile            # Docker container configuration
├── docker-compose.yaml   # Docker Compose configuration
├── .env                  # Configuration (create from .env.example)
├── common/               # Modular architecture components
│   ├── __init__.py       # Package exports (38 lines)
│   ├── README.md         # Architecture documentation
│   ├── config.py         # Environment & configuration (88 lines)
│   ├── nasa_search.py    # RAG implementation (87 lines)
│   ├── mcp_client.py     # MCP integration (138 lines)
│   ├── agent_factory.py  # Agent creation (79 lines)
│   └── thinking_spinner.py # UI components (67 lines)
├── data/                 # Source PDF documents (auto-downloaded)
│   ├── nasa_se_handbook.pdf
│   ├── artemis_i_press_kit.pdf
│   └── clps_press_kit.pdf
├── chroma_db/            # Vector database
└── .venv/                # Python virtual environment

添加新功能

1. 新文档类型：修改 ingest.py 支持其他格式
2. 自定义提示：更新 common/nasa_search.py 提示模板
3. 其他工具：向添加新工具 common/agent_factory.py 工具清单
4. 新集成：扩展 common/mcp_client.py 用于其他MCP服务器
5. 配置：向添加新设置 common/config.py 环境管理
6. 监控：将度量集合添加到现有调试工具中

模块化架构的优点

• 单一责任：每个模块都有一个明确的目的
• 可测试性：组件可以独立进行单元测试
• 可重用性：通用模块可用于其他项目
• 可维护性：更改仅限于特定组件
• 可扩展性：无需修改现有代码即可轻松添加新功能

测试

# Unit testing
make test-components

# Integration testing
make debug

# Performance testing
make debug-embeddings

# End-to-end testing
make test-retrieval

代码质量

• 类型提示：所有函数都包含类型注释
• 错误处理：通过用户友好的消息进行全面的异常处理
• 日志记录：用于故障排除的内置调试输出
• 文档：内联注释和文档字符串

🤝 贡献

入门指南

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/new-capability
3. 进行更改
4. 彻底测试： make debug
5. 提交拉取请求

开发指南

• 为所有函数添加类型提示
• 包括全面的错误处理
• 更新新功能的文档
• 使用测试所有更改 make debug

报告问题

在报告问题时，请包括：

1. 系统信息：输出 make debug-env
2. 错误消息：完整的回溯（如果可用）
3. 重现步骤：复制的最小示例
4. 预期与实际你的期望与实际情况

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 美国国家航空航天局：提供全面的技术文件
• LangChain：用于强大的文档处理框架
• OpenAI：强大的嵌入和生成功能
• 色度：用于高效的矢量数据库操作