Skip to content

feat: cookbook draft #336

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: dev
Choose a base branch
from
Draft

feat: cookbook draft #336

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c1c321b
feat: add cookbook
CaralHsi Sep 22, 2025
ca12136
feat: add cookbook
CaralHsi Sep 22, 2025
a0c5bda
feat: add cookbook chapter3
CaralHsi Sep 22, 2025
4d847c1
Merge branch 'dev' into feat/cookbook-draft
CaralHsi Sep 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 152 additions & 0 deletions examples/cookbook/chapter1/API/1/test_memos_setup_api_mode.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
# test_memos_setup_api_mode.py
# 🎯 API模式验证脚本 - 使用OpenAI API和MOS.simple()
import os
import sys

from dotenv import load_dotenv


def check_openai_environment():
"""🎯 检查OpenAI环境变量配置"""
print("🔍 检查OpenAI环境变量配置...")

# 加载.env文件
load_dotenv()

# 检查OpenAI配置
openai_key = os.getenv("OPENAI_API_KEY")
openai_base = os.getenv("OPENAI_API_BASE", "https://api.openai.com/v1")

print("📋 OpenAI环境变量状态:")

if openai_key:
masked_key = openai_key[:8] + "..." + openai_key[-4:] if len(openai_key) > 12 else "***"
print(f" ✅ OPENAI_API_KEY: {masked_key}")
print(f" ✅ OPENAI_API_BASE: {openai_base}")
return True
else:
print(" ❌ OPENAI_API_KEY: 未配置")
print(f" ❌ OPENAI_API_BASE: {openai_base}")
return False


def check_memos_installation():
"""🎯 检查MemOS安装状态"""
print("\n🔍 检查MemOS安装状态...")

try:
import memos

print(f"✅ MemOS版本: {memos.__version__}")

# 测试核心组件导入
from memos.configs.mem_os import MOSConfig
from memos.mem_cube.general import GeneralMemCube
from memos.mem_os.main import MOS

print("✅ 核心组件导入成功")
return True

except ImportError as e:
print(f"❌ 导入失败: {e}")
return False
except Exception as e:
print(f"❌ 其他错误: {e}")
return False


def test_api_functionality():
"""🎯 测试API模式功能"""
print("\n🔍 测试API模式功能...")

try:
from memos.mem_os.main import MOS

# 加载环境变量获取模型配置
load_dotenv()
chat_model = os.getenv("OPENAI_API_CHAT_MODEL", "gpt-4o-mini")
embed_model = os.getenv("OPENAI_API_EMBED_MODEL", "text-embedding-3-small")

print(f"🤖 使用聊天模型: {chat_model}")
print(f"🔍 使用嵌入模型: {embed_model}")

# 使用默认的MOS.simple()方法
print("🚀 创建MOS实例（使用MOS.simple()）...")
memory = MOS.simple()

print("✅ MOS.simple() 创建成功！")
print(f" 📊 用户ID: {memory.user_id}")
print(f" 📊 会话ID: {memory.session_id}")

# 测试添加记忆
print("\n🧠 测试添加记忆...")
memory.add(memory_content="这是一个API模式的测试记忆")
print("✅ 记忆添加成功！")

# 测试聊天功能
print("\n💬 测试聊天功能...")
response = memory.chat("我刚才添加了什么记忆？")
print(f"✅ 聊天响应: {response}")

# 测试搜索功能
print("\n🔍 测试搜索功能...")
search_results = memory.search("测试记忆", top_k=3)
if search_results and search_results.get("text_mem"):
print(f"✅ 搜索成功，找到 {len(search_results['text_mem'])} 个结果")
else:
print("⚠️ 搜索未返回结果")

print("✅ API模式功能测试成功！")
return True

except Exception as e:
print(f"❌ API模式功能测试失败: {e}")
print("💡 提示：请检查OpenAI API密钥和网络连接。")
return False


def main():
"""🎯 API模式主验证流程"""
print("🚀 开始MemOS API模式环境验证...\n")

# 步骤1: 检查OpenAI环境变量
env_ok = check_openai_environment()

# 步骤2: 检查安装状态
install_ok = check_memos_installation()

# 步骤3: 测试功能
if env_ok and install_ok:
func_ok = test_api_functionality()
else:
func_ok = False
if not env_ok:
print("\n⚠️ 由于OpenAI环境变量配置不完整，跳过功能测试")
elif not install_ok:
print("\n⚠️ 由于MemOS安装失败，跳过功能测试")

# 总结
print("\n" + "=" * 50)
print("📊 API模式验证结果总结:")
print(f" OpenAI环境变量: {'✅ 通过' if env_ok else '❌ 失败'}")
print(f" MemOS安装: {'✅ 通过' if install_ok else '❌ 失败'}")
print(f" 功能测试: {'✅ 通过' if func_ok else '❌ 失败'}")

if env_ok and install_ok and func_ok:
print("\n🎉 恭喜！MemOS API模式环境配置完全成功！")
print("💡 你现在可以开始使用MemOS API模式了。")
elif install_ok and env_ok:
print("\n⚠️ MemOS已安装，OpenAI已配置，但功能测试失败。")
print("💡 请检查OpenAI API密钥是否有效，网络连接是否正常。")
elif install_ok:
print("\n⚠️ MemOS已安装，但需要配置OpenAI环境变量才能正常使用。")
print("💡 请在.env文件中配置OPENAI_API_KEY。")
else:
print("\n❌ 环境配置存在问题，请检查上述错误信息。")

return bool(env_ok and install_ok and func_ok)


if __name__ == "__main__":
success = main()
sys.exit(0 if success else 1)
211 changes: 211 additions & 0 deletions examples/cookbook/chapter1/API/2/create_memcube_with_memreader_api.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,211 @@
# create_memcube_with_memreader_api.py
# 🎯 使用MemReader创建MemCube的完整流程 (API版)
import os
import uuid

from dotenv import load_dotenv

from memos.configs.mem_cube import GeneralMemCubeConfig
from memos.configs.mem_reader import MemReaderConfigFactory
from memos.mem_cube.general import GeneralMemCube
from memos.mem_reader.factory import MemReaderFactory


# 加载环境变量
load_dotenv()

# 获取OpenAI配置
openai_key = os.getenv("OPENAI_API_KEY")
openai_base = os.getenv("OPENAI_API_BASE", "https://api.openai.com/v1")

if not openai_key:
raise ValueError("❌ 未配置OPENAI_API_KEY。请在.env文件中配置OpenAI API密钥。")

print("✅ 检测到OpenAI API模式")

# 获取MemOS配置
user_id = os.getenv("MOS_USER_ID", "default_user")
top_k = int(os.getenv("MOS_TOP_K", "5"))

# 获取模型配置
chat_model = os.getenv("OPENAI_API_CHAT_MODEL", "gpt-4o-mini")
embed_model = os.getenv("OPENAI_API_EMBED_MODEL", "text-embedding-3-small")


def create_memcube_with_memreader():
"""
🎯 使用MemReader创建MemCube的完整流程 (API版)
"""

print("🔧 创建MemCube配置...")

print(f"🤖 使用聊天模型: {chat_model}")
print(f"🔍 使用嵌入模型: {embed_model}")

# OpenAI模式配置
cube_config = {
"user_id": user_id,
"cube_id": f"{user_id}_company_handbook_cube",
"text_mem": {
"backend": "general_text",
"config": {
"extractor_llm": {
"backend": "openai",
"config": {
"model_name_or_path": chat_model,
"temperature": 0.8,
"max_tokens": 8192,
"top_p": 0.9,
"top_k": 50,
"api_key": openai_key,
"api_base": openai_base,
},
},
"embedder": {
"backend": "universal_api",
"config": {
"provider": "openai",
"api_key": openai_key,
"model_name_or_path": embed_model,
"base_url": openai_base,
},
},
"vector_db": {
"backend": "qdrant",
"config": {
"collection_name": f"{user_id}_company_handbook",
"vector_dimension": 1536,
"distance_metric": "cosine",
},
},
},
},
"act_mem": {"backend": "uninitialized"},
"para_mem": {"backend": "uninitialized"},
}

# 创建MemCube实例
config_obj = GeneralMemCubeConfig.model_validate(cube_config)
mem_cube = GeneralMemCube(config_obj)

print("✅ MemCube创建成功！")
print(f" 📊 用户ID: {mem_cube.config.user_id}")
print(f" 📊 MemCube ID: {mem_cube.config.cube_id}")
print(f" 📊 文本记忆后端: {mem_cube.config.text_mem.backend}")
print(f" 🔍 嵌入模型: {embed_model} (OpenAI)")
print(" 🎯 配置模式: OPENAI API")

return mem_cube


def create_memreader_config():
"""
🎯 创建MemReader配置
"""

# 加载环境变量
load_dotenv()

# 获取OpenAI配置
openai_key = os.getenv("OPENAI_API_KEY")
openai_base = os.getenv("OPENAI_API_BASE", "https://api.openai.com/v1")

# 获取模型配置
chat_model = os.getenv("OPENAI_API_CHAT_MODEL", "gpt-4o-mini")
embed_model = os.getenv("OPENAI_API_EMBED_MODEL", "text-embedding-3-small")

# MemReader配置
mem_reader_config = MemReaderConfigFactory(
backend="simple_struct",
config={
"llm": {
"backend": "openai",
"config": {
"model_name_or_path": chat_model,
"temperature": 0.8,
"max_tokens": 8192,
"top_p": 0.9,
"top_k": 50,
"api_key": openai_key,
"api_base": openai_base,
},
},
"embedder": {
"backend": "universal_api",
"config": {
"provider": "openai",
"api_key": openai_key,
"model_name_or_path": embed_model,
"base_url": openai_base,
},
},
"chunker": {
"backend": "sentence",
"config": {"chunk_size": 64, "chunk_overlap": 20, "min_sentences_per_chunk": 1},
},
"remove_prompt_example": False,
},
)

return mem_reader_config


def load_document_to_memcube(mem_cube, doc_path):
"""
🎯 使用MemReader加载文档到MemCube
"""

print(f"\n📖 使用MemReader读取文档: {doc_path}")

# 创建MemReader
mem_reader_config = create_memreader_config()
mem_reader = MemReaderFactory.from_config(mem_reader_config)

# 准备文档数据
print("📄 准备文档数据...")
documents = [doc_path] # MemReader期望的是文档路径列表

# 使用MemReader处理文档
print("🧠 使用MemReader提取记忆...")
memories = mem_reader.get_memory(
documents,
type="doc",
info={"user_id": mem_cube.config.user_id, "session_id": str(uuid.uuid4())},
)

print(f"📚 MemReader生成了 {len(memories)} 个记忆片段")

# 添加记忆到MemCube
print("💾 添加记忆到MemCube...")
for mem in memories:
mem_cube.text_mem.add(mem)

print(f"✅ 成功添加 {len(memories)} 个记忆片段到MemCube")

# 输出基本信息
print("\n📊 MemCube基本信息:")
print(f" 📁 文档来源: {doc_path}")
print(f" 📝 记忆片段数量: {len(memories)}")
print(" 🏷️ 文档类型: company_handbook")
print(" 💾 向量数据库: Qdrant (内存模式，释放内存即删除)")
print(f" 🔍 嵌入模型: {embed_model} (OpenAI)")
print(" 🎯 配置模式: OPENAI API")
print(" 🧠 记忆提取器: MemReader (simple_struct)")

return mem_cube


if __name__ == "__main__":
print("🚀 开始使用MemReader创建文档MemCube (API版)...")

# 创建MemCube
mem_cube = create_memcube_with_memreader()

# 加载文档
import os

current_dir = os.path.dirname(os.path.abspath(__file__))
doc_path = os.path.join(current_dir, "company_handbook.txt")
load_document_to_memcube(mem_cube, doc_path)

print("\n🎉 MemCube创建完成！")
Loading
Loading