Metadata-Version: 2.1
Name: ai-hello
Version: 0.1.0
Summary: Agent development framework with OpenAI-compatible LLM adapters, tools, memory, and RAG.
Author: AiHello Team
License: MIT License
        
        Copyright (c) 2026 AiHello Team
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://gitee.com/zhangman995746185/ai_hello
Project-URL: Repository, https://gitee.com/zhangman995746185/ai_hello
Keywords: agent,llm,rag,openai,langchain,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohappyeyeballs==2.6.1
Requires-Dist: aiohttp==3.13.5
Requires-Dist: aiosignal==1.4.0
Requires-Dist: annotated-types==0.7.0
Requires-Dist: anyio==4.13.0
Requires-Dist: attrs==26.1.0
Requires-Dist: certifi==2026.4.22
Requires-Dist: cffi==2.0.0
Requires-Dist: charset-normalizer==3.4.7
Requires-Dist: colorama==0.4.6
Requires-Dist: cryptography==47.0.0
Requires-Dist: dashscope==1.25.17
Requires-Dist: dataclasses-json==0.6.7
Requires-Dist: distro==1.9.0
Requires-Dist: frozenlist==1.8.0
Requires-Dist: greenlet==3.4.0
Requires-Dist: h11==0.16.0
Requires-Dist: httpcore==1.0.9
Requires-Dist: httpx==0.28.1
Requires-Dist: httpx-sse==0.4.3
Requires-Dist: idna==3.13
Requires-Dist: jiter==0.14.0
Requires-Dist: jsonpatch==1.33
Requires-Dist: jsonpointer==3.1.1
Requires-Dist: langchain==1.2.15
Requires-Dist: langchain-classic==1.0.4
Requires-Dist: langchain-community==0.4.1
Requires-Dist: langchain-core==1.3.2
Requires-Dist: langchain-protocol==0.0.12
Requires-Dist: langchain-text-splitters==1.1.2
Requires-Dist: langgraph==1.1.9
Requires-Dist: langgraph-checkpoint==4.0.2
Requires-Dist: langgraph-prebuilt==1.0.11
Requires-Dist: langgraph-sdk==0.3.13
Requires-Dist: langsmith==0.7.36
Requires-Dist: marshmallow==3.26.2
Requires-Dist: multidict==6.7.1
Requires-Dist: mypy-extensions==1.1.0
Requires-Dist: numpy==2.4.4
Requires-Dist: openai==2.32.0
Requires-Dist: orjson==3.11.8
Requires-Dist: ormsgpack==1.12.2
Requires-Dist: packaging==26.2
Requires-Dist: propcache==0.4.1
Requires-Dist: pycparser==3.0
Requires-Dist: pydantic==2.13.3
Requires-Dist: pydantic-settings==2.14.0
Requires-Dist: pydantic-core==2.46.3
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: PyYAML==6.0.3
Requires-Dist: regex==2026.4.4
Requires-Dist: requests==2.33.1
Requires-Dist: requests-toolbelt==1.0.0
Requires-Dist: sniffio==1.3.1
Requires-Dist: SQLAlchemy==2.0.49
Requires-Dist: tavily-python==0.7.23
Requires-Dist: tenacity==9.1.4
Requires-Dist: tiktoken==0.12.0
Requires-Dist: tqdm==4.67.3
Requires-Dist: typing-inspect==0.9.0
Requires-Dist: typing-inspection==0.4.2
Requires-Dist: typing-extensions==4.15.0
Requires-Dist: urllib3==2.6.3
Requires-Dist: uuid-utils==0.14.1
Requires-Dist: websocket-client==1.9.0
Requires-Dist: xxhash==3.7.0
Requires-Dist: yarl==1.23.0
Requires-Dist: zstandard==0.25.0
Requires-Dist: hello-agents
Requires-Dist: qdrant-client
Requires-Dist: markitdown
Requires-Dist: paramiko

# AiHello - 智能 Agent 开发框架

<div align="center">

![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)
![LangChain](https://img.shields.io/badge/LangChain-1.2.15-orange.svg)

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

[特性](#-核心特性) • [快速开始](#-快速开始) • [文档](#-文档) • [贡献](#-贡献)

</div>

---

## 📖 项目简介

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️⃣ 安装步骤

```bash
# 克隆项目
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️⃣ 启动数据库服务

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

# 查看服务状态
docker compose ps
```

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

### 4️⃣ 配置环境变量

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

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

**运行时数据目录（推荐）**

```bash
# Windows
set AI_HELLO_HOME=%USERPROFILE%\.ai_hello

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

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

**关键配置项：**

```env
# ==================== 大模型配置 ====================
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 调用

```python
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

```python
from agent.traveller_agent import Traveller

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

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

#### 示例 3：使用记忆系统

```python
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 引擎

```python
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：**

```python
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**：终端命令执行

**注册自定义工具：**

```python
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 中的文档结构关系提升检索精度

**使用示例：**

```python
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 向量数据库：**

```env
# 本地部署
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 图数据库：**

```env
# 本地部署
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 模型：**

```env
# 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`
- ✅ 输入参数需进行有效性校验

### 调试技巧

**启用调试模式：**

```python
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'`

**解决方案：**
```bash
# 确保已激活虚拟环境
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`

**解决方案：**
```python
# 检查实际维度
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**

**贡献前请阅读：**
- [代码规范](#代码规范)
- [提交指南](CONTRIBUTING.md)（待补充）

---

## 📝 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

---

## 🙏 致谢

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

- **[LangChain](https://langchain.com/)** - Agent 框架
- **[OpenAI](https://openai.com/)** - LLM API
- **[Qdrant](https://qdrant.tech/)** - 向量数据库
- **[Neo4j](https://neo4j.com/)** - 图数据库
- **[智谱 AI](https://open.bigmodel.cn/)** - GLM 模型
- **[阿里云](https://dashscope.aliyun.com/)** - 通义千问模型
- **[Hello-Agents](https://github.com/datawhalechina/Hello-Agents)** - Agent 框架学习参考

---

## 📧 联系方式

- **Issue**: [GitHub Issues](https://github.com/your-repo/ai_hello/issues)
- **Email**: your-email@example.com

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

---

<div align="center">

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

Made with ❤️ by AiHello Team

</div>
