ai-hello 0.1.2

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

AiHello - 智能 Agent 开发框架

📖 项目简介

AiHello 是一个基于 OpenAI 兼容接口的通用 Agent 开发框架，面向 Python 应用集成场景，提供模型适配、Agent 基类、记忆系统、RAG 检索、工具注册与协议层能力。

当前项目已经整理为标准 pip 包发布形态，默认以库的方式使用，不提供 CLI。

适用场景：

• 智能问答与对话系统
• 知识库检索与 RAG 应用
• 带记忆能力的 Agent
• 需要工具调用的自动化助手

✨ 核心特性

• 多模型支持：兼容 openai、zhipu、qwen、deepseek、ollama、vllm 等 OpenAI 兼容提供方
• 多层次记忆系统：工作记忆、情景记忆、语义记忆、感知记忆四类记忆管理
• 高级 RAG 引擎：支持文档导入、分块、向量检索、MQE、HyDE、重排序
• 灵活的工具系统：原生工具注册机制，支持动态注册与执行
• 协议层能力：提供 MCP、A2A、ANP 相关实现
• 标准包发布：支持直接 pip install ai-hello

---

🏗️ 软件架构

ai_hello/
├── ai_hello/              # 包元数据与运行时路径
├── agent/                 # Agent 核心层
│   ├── agent_base.py      # Agent 基类
│   └── base_type/         # 基础 Agent 类型
│       ├── simple_agent.py
│       ├── react_agent.py
│       ├── reflection_agent.py
│       └── plan_solve_agent.py
├── model/                 # 模型适配层
│   ├── openai_sdk_llm.py  # OpenAI SDK 原生接口
│   └── lanchain_llm.py    # LangChain 适配器
├── memory/                # 记忆与 RAG
│   ├── manager.py         # 记忆统一入口
│   ├── memory_base.py     # 记忆基类与配置
│   ├── types/             # 四类记忆实现
│   ├── rag/               # RAG 管线
│   ├── storage/           # 向量/文档/图存储
│   └── context/           # 上下文加载
├── tools/                 # 工具系统
│   ├── registry.py        # 工具注册表
│   ├── tools_base.py      # 工具基类
│   ├── chain.py           # 工具链
│   └── builtin/           # 内置工具
│       ├── calculator.py
│       ├── context_tool.py
│       ├── memory_tool.py
│       ├── note_tool.py
│       ├── rag_tool.py
│       ├── search.py
│       └── terminal_tool.py
├── protocols/             # 协议层
│   ├── mcp/
│   ├── a2a/
│   └── anp/
├── config/                # 配置管理
└── utils/                 # 消息、日志、辅助函数

---

🔧 安装教程

1. 环境要求

• Python 3.10+
• pip

2. 从 PyPI 安装

pip install ai-hello

3. 从源码安装

git clone <repository-url>
cd ai_hello
pip install .

开发时建议使用虚拟环境：

python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

4. 可选外部服务

如果你要使用 RAG、向量检索或图存储能力，通常还需要准备：

• Qdrant
• Neo4j

项目根目录保留了 docker-compose.yml，可用于本地启动依赖服务。

---

📦 pip 包使用方式

AiHello 当前以“整包库发布”的方式提供能力，不带命令行入口。安装后常用导入方式如下：

from ai_hello.model.openai_sdk_llm import AiHelloLLM
from ai_hello.agent.base_type.simple_agent import SimpleAgent
from ai_hello.memory.manager import MemoryManager
from ai_hello.tools.registry import ToolRegistry
from ai_hello import get_data_dir

建议最少配置一组 OpenAI 兼容接口环境变量：

# Windows PowerShell
$env:LLM_API_KEY="your-api-key"
$env:LLM_BASE_URL="https://api.openai.com/v1"
$env:LLM_MODEL_ID="gpt-4o-mini"

---

🚀 使用说明

1. 快速开始 - 使用 AiHelloLLM

from ai_hello.model.openai_sdk_llm import AiHelloLLM

llm = AiHelloLLM(provider="openai")

messages = [
    {"role": "user", "content": "你好，请介绍一下 AiHello。"}
]

response = llm.invoke(messages)
print(response)

2. 使用 SimpleAgent

from ai_hello.agent.base_type.simple_agent import SimpleAgent
from ai_hello.model.openai_sdk_llm import AiHelloLLM

llm = AiHelloLLM(provider="openai")

agent = SimpleAgent(
    name="assistant",
    llm=llm,
    system_prompt="你是一个简洁、可靠的开发助手。"
)

result = agent.run("解释一下什么是向量检索。")
print(result)

3. 使用记忆系统

from ai_hello.memory.manager import MemoryManager

memory_manager = MemoryManager(
    user_id="user_001",
    enable_working=True,
    enable_episodic=True,
    enable_semantic=True,
    enable_perceptual=False
)

memory_id = memory_manager.add_memory(
    content="用户偏好简洁的技术说明",
    memory_type="semantic",
    importance=0.8,
    auto_classify=False
)

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 ai_hello.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(result["score"])
    print(result["metadata"]["content"][:200])

5. 使用工具注册表

from ai_hello.tools.registry import ToolRegistry

registry = ToolRegistry()
registry.register_function(
    name="echo",
    description="返回原始输入",
    func=lambda text: f"echo: {text}"
)

print(registry.execute_tool("echo", "hello ai_hello"))

---

📂 运行时数据目录

安装后的默认数据目录规则如下：

• 设置了 AI_HELLO_DATA_DIR 时，直接使用该目录
• 设置了 AI_HELLO_HOME 时，使用 AI_HELLO_HOME/data
• 在源码仓库内运行时，默认使用仓库下的 data/
• 作为已安装包运行时：
  • Windows: %LOCALAPPDATA%\AiHello\data
  • Linux/macOS: $XDG_DATA_HOME/ai_hello/data 或 ~/.local/share/ai_hello/data

建议显式设置：

# Windows PowerShell
$env:AI_HELLO_HOME="$HOME\\.ai_hello"

Python 中可以查看：

from ai_hello import get_data_dir

print(get_data_dir())

---

📦 核心组件详解

1. Model 层

AiHelloLLM 是当前最核心的统一模型入口，特点包括：

• 参数优先，环境变量兜底
• 自动识别 Provider
• 支持流式与非流式调用
• 面向 OpenAI 兼容接口统一封装

2. Agent 层

当前内置的基础 Agent 类型包括：

• SimpleAgent
• ReActAgent
• ReflectionAgent
• PlanSolveAgent

它们都基于 AgentBase 扩展，可继续派生自定义 Agent。

3. Memory 层

四类记忆：

• working
• episodic
• semantic
• perceptual

MemoryManager 负责统一协调、检索、更新、遗忘和整合。

4. RAG 层

RAG 管线支持：

• 文本 / Markdown
• PDF
• Office 文档
• 图片
• 音频

并提供：

• 文档切分
• 向量化
• 检索
• 查询扩展
• 重排序

5. Tools 层

当前内置工具包括：

• calculator
• context
• memory
• note
• rag
• search
• terminal

---

🔍 常见问题

1. API 调用失败（401）

通常是 API Key 无效或未配置。

检查：

# Windows PowerShell
echo $env:LLM_API_KEY

2. Provider 检测不符合预期

如果你同时设置了多组环境变量，建议显式指定：

llm = AiHelloLLM(provider="zhipu")

3. Qdrant 连接失败

检查项：

• 本机服务是否已经启动
• QDRANT_URL 是否正确
• 云端场景下 QDRANT_API_KEY 是否正确

4. 向量维度不匹配

检查当前 embedding 实际维度：

from ai_hello.memory.embedding import EmbeddingModelManger

dimension = EmbeddingModelManger().get_dimension(1024)
print(dimension)

---

🛠️ 开发说明

• 当前包结构保留历史上的平铺模块布局，优先沿用现有导入路径
• 当前发布形态是库，不是 CLI
• RAG、Qdrant、Neo4j 等能力依赖外部服务，安装成功不等于这些服务已经可用

---

🤝 参与贡献

1. Fork 本仓库
2. 创建特性分支
3. 提交更改
4. 推送分支
5. 发起 Pull Request

---

📝 许可证

MIT