ai-hello 0.1.0

Agent development framework with OpenAI-compatible LLM adapters, tools, memory, and RAG.

AiHello - 智能 Agent 开发框架

基于 OpenAI SDK 的通用 Agent 开发框架

特性 • 快速开始 • 文档 • 贡献

---

📖 项目简介

AiHello 是一个功能完善的智能 Agent 开发框架，提供记忆管理、RAG（检索增强生成）、工具调用和多数据库支持。框架采用分层架构设计，支持快速构建基于大语言模型的复杂 AI 应用，如智能对话系统、知识问答助手和旅行规划 Agent 等。

✨ 核心特性

• 🤖 多模型支持：兼容智谱 GLM、通义千问、OpenAI、DeepSeek 等多种 LLM 提供商
• 🧠 多层次记忆系统：工作记忆、情景记忆、语义记忆、感知记忆四类记忆管理
• 🔍 高级 RAG 引擎：支持 MQE（多查询扩展）、HyDE（假设文档嵌入）、Cross-Encoder 重排序
• 🛠️ 灵活工具系统：原生 MCP 工具注册机制，支持动态工具注册与执行
• 💾 双数据库架构：Qdrant 向量库 + Neo4j 图数据库，支持本地 Docker 和云端部署
• 📨 统一消息接口：标准化的消息格式和通信协议
• 🌐 Web 界面：基于 Gradio 的智能问答助手界面

---

🏗️ 架构设计

整体架构

┌─────────────────────────────────────┐
│         Application Layer           │  # 应用层 (Gradio Web / CLI)
├─────────────────────────────────────┤
│          Agent Layer                │  # Agent 核心层
│  ┌──────────┬──────────┬──────────┐ │
│  │ ReAct    │Reflect   │ Simple   │ │
│  └──────────┴──────────┴──────────┘ │
├─────────────────────────────────────┤
│        Tool Layer (MCP)             │  # 工具调用层
│  ┌──────────┬──────────┬──────────┐ │
│  │Builtin   │ Travel   │ Custom   │ │
│  └──────────┴──────────┴──────────┘ │
├─────────────────────────────────────┤
│       Memory & RAG Layer            │  # 记忆与检索层
│  ┌──────────┬──────────┬──────────┐ │
│  │Working   │Episodic  │Semantic  │ │
│  └──────────┴──────────┴──────────┘ │
├─────────────────────────────────────┤
│        Model Adapter Layer          │  # 模型适配层
│  ┌────────────────────────────────┐ │
│  │  OpenAI SDK / LangChain        │ │
│  └────────────────────────────────┘ │
├─────────────────────────────────────┤
│      Storage Layer                  │  # 存储层
│  ┌──────────┬──────────┬──────────┐ │
│  │ Qdrant   │ Neo4j    │ SQLite   │ │
│  └──────────┴──────────┴──────────┘ │
└─────────────────────────────────────┘

目录结构

ai_hello/
├── agent/                    # Agent 核心层
│   ├── base_type/           # 基础 Agent 类型
│   │   ├── react_agent.py          # ReAct 模式 Agent
│   │   ├── reflection_agent.py     # 反思模式 Agent
│   │   ├── plan_solve_agent.py     # 计划解决模式 Agent
│   │   └── simple_agent.py         # 简单 Agent
│   ├── demo_test/           # 示例测试
│   ├── agent_base.py        # Agent 基类
│   └── traveller_agent.py   # 旅行规划 Agent
│
├── tools/                   # 工具系统
│   ├── builtin/             # 内置工具
│   │   ├── calculator.py    # 计算器
│   │   ├── context_tool.py  # 上下文工具
│   │   ├── memory_tool.py   # 记忆工具
│   │   ├── note_tool.py     # 笔记工具
│   │   ├── rag_tool.py      # RAG 工具
│   │   ├── search.py        # 搜索工具
│   │   └── terminal_tool.py # 终端工具
│   ├── travel/              # 旅行相关工具
│   │   ├── get_weather.py        # 天气查询
│   │   ├── get_attraction.py     # 景点查询
│   │   ├── get_search.py         # 搜索工具
│   │   └── ToolFactory.py        # 工具工厂
│   ├── registry.py          # 全局工具注册表
│   ├── tools_base.py        # 工具基类
│   ├── chain.py             # 工具链
│   └── async_executor.py    # 异步执行器
│
├── model/                   # 模型适配层
│   ├── openai_sdk_llm.py    # OpenAI SDK 原生接口（推荐）
│   └── lanchain_llm.py      # LangChain 适配器
│
├── memory/                  # 记忆管理层
│   ├── types/               # 四种记忆类型
│   │   ├── working.py       # 工作记忆（短期）
│   │   ├── episodic.py      # 情景记忆（事件）
│   │   ├── semantic.py      # 语义记忆（知识）
│   │   └── perceptual.py    # 感知记忆（多模态）
│   ├── rag/                 # RAG 引擎
│   │   ├── pipeline.py      # RAG 处理管道
│   │   └── document.py      # 文档处理
│   ├── storage/             # 存储后端
│   │   ├── qdrant_store.py  # Qdrant 向量存储
│   │   ├── neo4j_store.py   # Neo4j 图存储
│   │   ├── document_store.py# 文档存储
│   │   └── qdrant_settings.py # Qdrant 配置
│   ├── context/             # 上下文加载
│   │   └── context_loader.py
│   ├── manager.py           # 记忆管理器（统一入口）
│   ├── memory_base.py       # 记忆基类
│   └── embedding.py         # 嵌入模型管理
│
├── protocols/               # 通信协议
│   ├── mcp/                 # Model Context Protocol
│   │   ├── client.py        # MCP 客户端
│   │   ├── server.py        # MCP 服务端
│   │   └── utils.py         # 工具函数
│   ├── a2a/                 # Agent-to-Agent 协议
│   └── anp/                 # Agent Network Protocol
│
├── config/                  # 配置管理
│   ├── proj_config.py       # 项目配置
│   └── database_config.py   # 数据库配置
│
├── utils/                   # 工具函数
│   ├── message.py           # 消息系统
│   ├── exceptions.py        # 异常定义
│   ├── helpers.py           # 辅助函数
│   ├── logging.py           # 日志系统
│   └── serialization.py     # 序列化工具
│
├── data/                    # 数据目录
│   ├── notes/               # 笔记数据
│   └── README.md            # 数据说明
│
├── docker-compose.yml       # Docker 编排文件
├── requirements.txt         # Python 依赖
└── .env.example             # 环境变量示例

---

🚀 快速开始

1️⃣ 环境准备

系统要求：

• Python 3.10+
• Docker & Docker Compose（用于启动数据库服务）

2️⃣ 安装步骤

# 克隆项目
git clone <repository-url>
cd ai_hello

# 创建虚拟环境
python -m venv ai_hello_env

# 激活虚拟环境
# Windows:
ai_hello_env\Scripts\activate
# Linux/Mac:
source ai_hello_env/bin/activate

# 安装依赖
pip install -r requirements.txt

# 以完整 pip 包形式安装当前项目
pip install .

3️⃣ 启动数据库服务

# 使用 Docker Compose 启动 Qdrant 和 Neo4j
docker compose up -d

# 查看服务状态
docker compose ps

提示：若使用云端数据库（Qdrant Cloud / Neo4j Aura），跳过此步骤，直接在 .env 中配置云端地址。

4️⃣ 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填写必要的配置

运行时数据目录（推荐）

# Windows
set AI_HELLO_HOME=%USERPROFILE%\.ai_hello

# Linux / Mac
export AI_HELLO_HOME=$HOME/.ai_hello

安装后的默认数据会写入 AI_HELLO_HOME/data；如果在源码仓库内直接运行，则默认继续使用仓库下的 data/ 目录。

关键配置项：

# ==================== 大模型配置 ====================
LLM_MODEL_ID=glm-4.5-air
LLM_API_KEY=your_api_key_here
LLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4
LLM_TIMEOUT=60

# ==================== 向量数据库 ====================
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION=test
QDRANT_VECTOR_SIZE=1024
QDRANT_DISTANCE=cosine

# ==================== 图数据库 ====================
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=hello-agents-password

# ==================== Embedding 配置 ====================
EMBED_MODEL_TYPE=dashscope
EMBED_MODEL_NAME=text-embedding-v3
EMBED_API_KEY=sk-your-dashscope-api-key

# ==================== 搜索引擎（可选）====================
SERPAPI_API_KEY=your_serpapi_key
TAVILY_API_KEY=tvly-dev-your-tavily-key

5️⃣ 运行示例

示例 1：基础 LLM 调用

from model.openai_sdk_llm import AiHelloLLM

# 创建 LLM 实例
llm = AiHelloLLM(provider='zhipu')

# 非流式调用
messages = [{"role": "user", "content": "你好，请介绍一下你自己"}]
response = llm.invoke(messages)
print(response)

# 流式调用
for chunk in llm.think(messages):
    print(chunk, end="", flush=True)

示例 2：使用 Agent

from agent.traveller_agent import Traveller

# 创建旅行规划 Agent
agent = Traveller()

# 运行 Agent
result = agent.run(
    "请帮我规划一次旅行，2个人情侣关系，五月1号从成都出发去云南昆明玩3天，预算3000，喜欢美食。"
)
print(result)

示例 3：使用记忆系统

from memory.manager import MemoryManager

# 创建记忆管理器
memory_manager = MemoryManager(
    user_id="user_001",
    enable_working=True,
    enable_episodic=True,
    enable_semantic=True
)

# 添加记忆
memory_id = memory_manager.add_memory(
    content="用户喜欢川菜和火锅",
    memory_type="semantic",
    importance=0.8
)

# 检索记忆
memories = memory_manager.retrieve_memories(
    query="用户喜欢的食物",
    limit=5,
    min_importance=0.5
)

for memory in memories:
    print(f"[{memory.memory_type}] {memory.content}")

示例 4：使用 RAG 引擎

from memory.rag.pipeline import load_and_chunk_texts, index_chunks, search_vectors

# 加载并分块文档
chunks = load_and_chunk_texts(
    paths=["data/raw_data/document.pdf"],
    chunk_size=800,
    chunk_overlap=100,
    namespace="my_knowledge"
)

# 索引到向量数据库
index_chunks(chunks=chunks, rag_namespace="my_knowledge")

# 搜索相关内容
results = search_vectors(
    query="什么是人工智能？",
    top_k=5,
    rag_namespace="my_knowledge"
)

for result in results:
    print(f"相似度: {result['score']}")
    print(f"内容: {result['metadata']['content'][:200]}...")

---

📚 文档

核心组件详解

1. Agent 层

Agent 是框架的核心抽象，负责协调 LLM、工具和记忆的交互。

支持的 Agent 类型：

类型	说明	适用场景
SimpleAgent	简单的问答 Agent	基础对话
ReActAgent	推理 + 行动的 Agent	需要工具调用的复杂任务
ReflectionAgent	具有自我反思能力的 Agent	需要高质量输出的场景
PlanSolveAgent	先规划后执行的 Agent	复杂多步骤任务
TravellerAgent	旅行规划专用 Agent	旅行行程规划

创建自定义 Agent：

from agent.agent_base import AgentBase
from model.openai_sdk_llm import AiHelloLLM

class MyAgent(AgentBase):
    def __init__(self):
        llm = AiHelloLLM(provider='zhipu')
        system_prompt = "你是一个专业的助手..."
        super().__init__(name="my_agent", llm=llm, system_prompt=system_prompt)
    
    def run(self, input_text: str, **kwargs) -> str:
        messages = self._build_messages(input_text)
        response = self.llm.invoke(messages)
        self._record_history(input_text, response)
        return response

2. 工具系统（MCP）

MCP（Model Context Protocol）提供统一的工具注册和执行机制。

内置工具：

• Calculator：数学计算
• SearchTool：网络搜索（SerpAPI/Tavily）
• MemoryTool：记忆读写操作
• RAGTool：知识库检索
• NoteTool：笔记管理
• TerminalTool：终端命令执行

注册自定义工具：

from tools.tools_base import Tool, ToolParameter
from tools.registry import global_registry

class WeatherTool(Tool):
    def __init__(self):
        super().__init__(
            name="get_weather",
            description="查询指定城市的天气"
        )
    
    def run(self, parameters: dict) -> str:
        city = parameters.get("city", "北京")
        # 实现天气查询逻辑
        return f"{city} 今天晴，25°C"
    
    def get_parameters(self) -> list[ToolParameter]:
        return [
            ToolParameter(
                name="city",
                type="string",
                description="城市名称",
                required=True
            )
        ]

# 注册工具
global_registry.register_tool(WeatherTool())

# 执行工具
result = global_registry.execute_tool("get_weather", {"city": "上海"})

3. 记忆系统

框架提供四种记忆类型，分别对应不同的存储策略和用途。

记忆类型对比：

类型	用途	存储	生命周期
工作记忆	当前对话上下文	SQLite	短期
情景记忆	历史交互事件	SQLite + 向量	中长期
语义记忆	领域知识和事实	向量 + 图数据库	长期
感知记忆	多模态特征	向量数据库	长期

记忆管理功能：

• ✅ 自动分类：根据内容关键词分配到合适的记忆类型
• ✅ 重要性评估：基于内容长度、关键词计算重要性分数
• ✅ 记忆遗忘：支持基于重要性、时间、容量的遗忘策略
• ✅ 记忆整合：将重要的短期记忆转换为长期记忆

4. RAG 引擎

处理流程：

文档加载 → Markdown 转换 → Token 分块 → 向量化 → 索引存储
                                              ↓
用户查询 → 查询扩展(MQE/HyDE) → 向量检索 → 重排序 → 结果融合

高级检索技术：

1. MQE (Multi-Query Expansion)：使用 LLM 生成多个语义等价的查询，提升召回率
2. HyDE (Hypothetical Document Embeddings)：先生成假设答案，再用答案进行检索
3. Cross-Encoder 重排序：使用交叉编码器对初步检索结果重新排序
4. 图信号增强：利用 Neo4j 中的文档结构关系提升检索精度

使用示例：

from memory.rag.pipeline import search_vectors_expanded, rerank_with_cross_encoder

# 使用高级检索
results = search_vectors_expanded(
    query="深度学习的应用场景",
    top_k=10,
    enable_mqe=True,
    mqe_expansions=3,
    enable_hyde=True,
    rag_namespace="my_knowledge"
)

# 重排序
reranked = rerank_with_cross_encoder(
    query="深度学习的应用场景",
    items=results,
    top_k=5
)

---

🔧 配置说明

环境变量优先级

所有配置遵循以下优先级顺序：

1. 代码中显式传入的参数
2. .env 文件中的配置
3. 系统环境变量
4. 默认值

数据库配置

Qdrant 向量数据库：

# 本地部署
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=              # 留空表示不使用 API Key

# 云端部署
QDRANT_URL=https://your-cluster.qdrant.tech
QDRANT_API_KEY=your-api-key

# 集合配置
QDRANT_COLLECTION=test
QDRANT_VECTOR_SIZE=1024      # 需与 Embedding 模型维度一致
QDRANT_DISTANCE=cosine       # cosine / dot / euclidean

Neo4j 图数据库：

# 本地部署
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=hello-agents-password

# 云端部署（Neo4j Aura）
NEO4J_URI=neo4j+s://your-instance.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password

模型配置

支持的 Provider：

Provider	说明	环境变量
zhipu	智谱 AI (GLM)	LLM_API_KEY, LLM_BASE_URL
qwen	通义千问	LLM_API_KEY, LLM_BASE_URL
openai	OpenAI GPT	OPENAI_API_KEY
deepseek	DeepSeek	LLM_API_KEY
kimi	月之暗面	LLM_API_KEY
ollama	本地 Ollama	LLM_BASE_URL=http://localhost:11434

Embedding 模型：

# DashScope（推荐）
EMBED_MODEL_TYPE=dashscope
EMBED_MODEL_NAME=text-embedding-v3
EMBED_API_KEY=sk-your-key

# 本地模型
EMBED_MODEL_TYPE=local
EMBED_MODEL_NAME=BAAI/bge-large-zh

---

🛠️ 开发指南

代码规范

• ✅ 所有代码需添加详细注释
• ✅ 使用统一的日志模块（utils.logging）
• ✅ 避免循环导入，保持模块间单向依赖
• ✅ 异常处理需捕获具体异常类型，禁止裸 except Exception
• ✅ 输入参数需进行有效性校验

调试技巧

启用调试模式：

from config.proj_config import ProjConfig

ProjConfig.DEBUG = True
ProjConfig.LOG_LEVEL = "DEBUG"

查看日志：

日志包含文件名、函数名和行号信息，便于快速定位问题。

2024-01-01 12:00:00 [DEBUG] agent_base.py:run:45 - Agent 开始执行
2024-01-01 12:00:01 [INFO] openai_sdk_llm.py:invoke:120 - LLM 调用成功

常见问题

1. 导入错误

问题： ModuleNotFoundError: No module named 'xxx'

解决方案：

# 确保已激活虚拟环境
source ai_hello_env/bin/activate

# 确保项目根目录在 PYTHONPATH 中
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

2. API 调用失败（401 错误）

原因： API Key 无效或过期

解决方案：

• 检查 .env 文件中的 API Key 是否正确
• 访问对应平台重新生成 API Key
  • 智谱 AI: https://open.bigmodel.cn/
  • 通义千问: https://dashscope.aliyun.com/

3. Qdrant 连接失败

检查清单：

• ✅ 确认 Docker 容器正在运行：docker compose ps
• ✅ 检查端口是否被占用：netstat -an | grep 6333
• ✅ 验证配置：echo $QDRANT_URL

4. 向量维度不匹配

错误信息： expected dim: 384, got 1024

解决方案：

# 检查实际维度
from memory.embedding import EmbeddingModelManger
dimension = EmbeddingModelManger().get_dimension(1024)
print(f"实际维度: {dimension}")

# 更新 .env 中的 QDRANT_VECTOR_SIZE
# 或删除旧集合并重新创建

5. VSCode 波浪线警告

问题： 代码修复后仍显示导入错误

解决方案：

• 重启 Python 语言服务器（Cmd/Ctrl + Shift + P → "Python: Restart Language Server"）
• 或重启 VSCode

---

📊 性能优化建议

Token 优化

• ✅ 将 system_prompt 转换为 SystemMessage，在初始化时注入
• ✅ 后续对话只传递用户输入和历史记录，避免重复拼接
• ✅ 使用结构化消息对象（HumanMessage、AIMessage）

检索优化

• ✅ 合理设置 chunk_size（推荐 500-1000 tokens）
• ✅ 启用 MQE 和 HyDE 提升召回率
• ✅ 使用 Cross-Encoder 重排序提升精度
• ✅ 根据场景调整 top_k 参数

数据库优化

• ✅ 定期清理低重要性记忆
• ✅ 为常用查询字段建立索引
• ✅ 使用命名空间隔离不同业务数据

---

🤝 参与贡献

我们欢迎任何形式的贡献！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

贡献前请阅读：

• 代码规范
• 提交指南（待补充）

---

📝 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

---

🙏 致谢

感谢以下开源项目和技术的支持：

• LangChain - Agent 框架
• OpenAI - LLM API
• Qdrant - 向量数据库
• Neo4j - 图数据库
• 智谱 AI - GLM 模型
• 阿里云 - 通义千问模型
• Hello-Agents - Agent 框架学习参考

---

📧 联系方式

• Issue: GitHub Issues
• Email: [e-mail]

如有问题或建议，欢迎提交 Issue 或联系维护团队。

---

⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！

Made with ❤️ by AiHello Team