hello-agents 第八章学习分享：记忆与检索

任意格式文档 → MarkItDown 统一转 Markdown → 按标题智能分块 → 向量化 → 存进向量库
用户提问 → 向量检索（可选 MQE/HyDE 加持）→ 检索结果塞进 prompt → LLM 生成答案

pip install "hello-agents==0.2.0"

# memory_demo.py —— 教程 8.2.2 的记忆示例（离线可跑，无需任何 API key）
from hello_agents.tools import MemoryTool

tool = MemoryTool(user_id="user123", memory_types=["working"])

# 存三条记忆，importance 是"重要性打分"，0 到 1
tool.execute("add", content="用户张三是一名Python开发者，专注机器学习和数据分析",
             memory_type="working", importance=0.8)
tool.execute("add", content="李四是前端工程师，擅长React和Vue.js",
             memory_type="working", importance=0.7)
tool.execute("add", content="王五是产品经理，负责用户体验设计",
             memory_type="working", importance=0.6)

print("=== 搜索：前端工程师（教程原例的搜索词） ===")
print(tool.execute("search", query="前端工程师", limit=3))

print("\n=== 我多试了一步：换个说法搜「写网页的」 ===")
print(tool.execute("search", query="写网页的", limit=3))

print("\n=== 遗忘：把重要性低于 0.65 的记忆清掉（教程的三种遗忘策略之一） ===")
print(tool.execute("forget", strategy="importance_based", threshold=0.65))

print("\n=== 再搜：产品经理（应该找不到了） ===")
print(tool.execute("search", query="产品经理", limit=3))

print("\n=== 记忆摘要（教程原例的最后一步） ===")
print(tool.execute("summary"))

INFO:hello_agents.memory.manager:MemoryManager初始化完成，启用记忆类型: ['working']
INFO:hello_agents.memory.manager:记忆遗忘完成: 1 条记忆
=== 搜索：前端工程师（教程原例的搜索词） ===
🔍 找到 1 条相关记忆:
1. [工作记忆] 李四是前端工程师，擅长React和Vue.js (重要性: 0.70)

=== 我多试了一步：换个说法搜「写网页的」 ===
🔍 未找到与 '写网页的' 相关的记忆

=== 遗忘：把重要性低于 0.65 的记忆清掉（教程的三种遗忘策略之一） ===
🧹 已遗忘 1 条记忆（策略: importance_based）

=== 再搜：产品经理（应该找不到了） ===
🔍 未找到与 '产品经理' 相关的记忆

=== 记忆摘要（教程原例的最后一步） ===
📊 记忆系统摘要
总记忆数: 2
当前会话: session_20261020_010251
对话轮次: 0

📋 记忆类型分布:
  • 工作记忆: 2 条 (平均重要性: 0.75)

最终得分 = 相关性 × 时间衰减 × 重要性权重
重要性权重 = 0.8 + importance × 0.4   # 取值范围 [0.8, 1.2]

pip install "hello-agents==0.2.0" "qdrant-client==1.12.1"

# rag_demo.py —— 教程 8.3.3「30秒上手RAG功能」的离线跑法
# 正式流程：.env 配好 QDRANT_URL / 百炼 EMBED_API_KEY / LLM 的 key，
# 把"离线补丁"整段删掉即可，主例子代码一字不用改。
import os
import re
import math
import hashlib
from collections import Counter

# ========== 离线补丁（共四小段，想连真服务就整段删掉） ==========

# 补丁1：Qdrant 改用纯内存模式（正式流程配 QDRANT_URL 即可）
import hello_agents.memory.storage.qdrant_store as qs
from qdrant_client import QdrantClient

def _init_memory_client(self):
    self.client = QdrantClient(location=":memory:")
    self._ensure_collection()

qs.QdrantVectorStore._initialize_client = _init_memory_client

# 补丁2：嵌入换成离线的"字符二元组哈希向量"（正式流程配百炼 API 即可）
from hello_agents.memory import embedding

class OfflineEmbedder(embedding.EmbeddingModel):
    def __init__(self, dim=512):
        self._dim = dim

    def _tokens(self, text):
        text = text.lower()
        words = re.findall(r"[a-z0-9]+", text)          # 英文按词
        cjk = re.findall(r"[\u4e00-\u9fff]", text)      # 中文按相邻两字拆
        return words + [cjk[i] + cjk[i+1] for i in range(len(cjk) - 1)]

    def encode(self, texts):
        single = isinstance(texts, str)
        inputs = [texts] if single else list(texts)
        out = []
        for t in inputs:
            vec = [0.0] * self._dim
            for tok, cnt in Counter(self._tokens(t)).items():
                idx = int(hashlib.md5(tok.encode()).hexdigest(), 16) % self._dim
                vec[idx] += cnt
            norm = math.sqrt(sum(x * x for x in vec)) or 1.0
            out.append([x / norm for x in vec])
        return out[0] if single else out

    @property
    def dimension(self):
        return self._dim

embedding._embedder = OfflineEmbedder()  # 注入全局单例，整条 RAG 流水线都用它

# 补丁3：LLM 客户端给个占位配置让它能初始化（ask 才会真调用，下面用不到）
os.environ.setdefault("OLLAMA_HOST", "http://localhost:11434/v1")

# 补丁4：静音离线模式下的无害日志（本地Qdrant的索引提示、占位LLM的健康检查重试）
import logging
for name in ("httpx2", "openai._base_client"):
    logging.getLogger(name).setLevel(logging.ERROR)
logging.getLogger().addFilter(
    type("F", (logging.Filter,),
         {"filter": staticmethod(lambda r: "Payload indexes" not in r.getMessage())})()
)

# ========== 以下完全是教程 8.3.3 的原例 ==========
from hello_agents.tools import RAGTool

# 创建RAG工具
rag_tool = RAGTool(
    knowledge_base_path="./knowledge_base",
    collection_name="test_collection",
    rag_namespace="test"
)

# 添加第一个知识
result1 = rag_tool.execute("add_text",
    text="Python是一种高级编程语言，由Guido van Rossum于1991年首次发布。Python的设计哲学强调代码的可读性和简洁的语法。",
    document_id="python_intro")
print(f"知识1: {result1}")

# 添加第二个知识
result2 = rag_tool.execute("add_text",
    text="机器学习是人工智能的一个分支，通过算法让计算机从数据中学习模式。主要包括监督学习、无监督学习和强化学习三种类型。",
    document_id="ml_basics")
print(f"知识2: {result2}")

# 添加第三个知识
result3 = rag_tool.execute("add_text",
    text="RAG（检索增强生成）是一种结合信息检索和文本生成的AI技术。它通过检索相关知识来增强大语言模型的生成能力。",
    document_id="rag_concept")
print(f"知识3: {result3}")

print("\n=== 搜索知识 ===")
result = rag_tool.execute("search",
    query="Python编程语言的历史",
    limit=3,
    min_score=0.1
)
print(result)

print("\n=== 知识库统计 ===")
result = rag_tool.execute("stats")
print(result)

INFO:hello_agents.memory.storage.qdrant_store:✅ 创建Qdrant集合: test_collection
✅ RAG工具初始化成功: namespace=test, collection=test_collection
[RAG] Universal loader start: files=1 chunk_size=800 overlap=100 ns=default
[RAG] Processing: ./knowledge_base/python_intro.md
[RAG] Universal loader done: total_chunks=1
[RAG] Embedding start: total_texts=1 batch_size=64
[RAG] Embedding progress: 1/1
[RAG] Qdrant upsert start: n=1
[RAG] Qdrant upsert done: 1 vectors indexed
知识1: ✅ 文本已添加到知识库: python_intro
📊 分块数量: 1
⏱️ 处理时间: 1860ms
📝 命名空间: default
（知识2、知识3 同样的一套入库日志，略）

=== 搜索知识 ===
搜索结果：

1. 文档: **./knowledge_base/python_intro.md** (相似度: 0.334)
   Python是一种高级编程语言，由Guido van Rossum于1991年首次发布。Python的设计哲学强调代码的可读性和简洁的语法。...

=== 知识库统计 ===
📊 **RAG 知识库统计**
📝 命名空间: default
📋 集合名称: test_collection
📂 存储根路径: ./knowledge_base
📦 存储类型: qdrant
📊 文档分块数: 3
🔢 向量维度: 512
📎 距离度量: Cosine

🟢 **系统状态**
✅ RAG 管道: 正常
✅ LLM 连接: 正常