✨🦋 illufly - 【幻蝶】基于记忆蒸馏、资料检索的自我进化智能体
✨🦋 illufly
illufly 是 illution butterfly 的缩写，中文为"幻蝶"。
illufly 是一个具有自我进化能力的 Agent 框架，目标是：基于自我进化，快速创作价值。
illufly 被设计为在意图猜测、问答经验、资料召回率、工具规划能力等各种场景下都具有自我进化能力。
本文作为开始，一步一步讲述各种场景下的自我进化如何实现。
请注意: 由于 illufly 还处于开发状态，为了加强自我进化能力，框架的一些概念会不断更新，使用时请锁定版本。
1 从内置的 RAG 能力开始讲起
illufly 使用时简单、直接、快速，但创造价值的场景却很丰富。
从 illufly.chat 导入一个封装好的大模型是最常见的开始方式。
from illufy.chat import ChatQwenChatQwen 是 ChatAgent 子类。
这一行代码很简单，但你会越来越惊奇地发现，这个 Agent 已经具备很多魔法能力。
1.1 连续对话
首先是连续对话能力：
from illufly.chat import ChatQwen
qwen = ChatQwen()
qwen("请你帮我写封一句话情书，深情又逗比的那种")
实际上，上述代码已经内置了一些功能特性：
- 流式输出 内置流输出
- 支持连续对话 问答过程是有记忆的，可以连续对话
qwen.memory1.2 内置 RAG 支持
使用 RAG（检索增强生成）是开发大模型应用时的常见场景。
illufly 内置了一些 RAG 实现策略，最简单的就是直接将背景知识添加到 Agent 中。
构建最朴素的 RAG 应用：
from illufly.chat import ChatQwen
声明大模型实例
qwen = ChatQwen(knowledge=[
"我的女朋友名字叫林徽因，我喜欢叫她「银子」",
"她喜欢叫我「金子」",
])
使用
qwen("请你帮我写封一句话情书，深情又逗比的那种")
qwen.memory[{'role': 'user', 'content': '回答时请参考已有知识：\n@knowledge\n我的女朋友名字叫林徽因，我喜欢叫她「银子」她喜欢叫我「金子」\n'}, {'role': 'assistant', 'content': 'ok'}, {'role': 'user', 'content': '请你帮我写封一句话情书，深情又逗比的那种'}, {'role': 'assistant', 'content': '"亲爱的银子，你是我生活中不可或缺的闪光点，没有你，我的人生将失去所有的金光璀璨，也少了许多欢声笑语，爱你的金子如是说。"'}]
将资料保存到文件并根据问题召回：
illufly 也支持传统的 RAG 流程：将文档切分成多个片段，再通过向量模型比较问题和文档片段，这个过程被称为「召回」，也就是从数据库中查找到文本相似的那部份文档片段。
你可以把资料整理为 markdown 文件，放入指定位置，比如 ./docs/gf.md 中，然后使用向量模型嵌入文档，再使用向量数据库检索，最后加载到大模型的提示语中。
在 illufly 框架中，这个过程依然非常简洁，你只负责声明实例就可以，其余的交给 illufly 实现。
from illufly.rag import TextEmbeddings, FaissDB
from illufly.chat import ChatQwen
声明向量数据库并加载指定位置的文档
db = FaissDB(embeddings=TextEmbeddings(), top_k=3)
db.load_dir("./docs")
声明大模型实例
qwen = ChatQwen(knowledge=[db])
使用
qwen("请你帮我写封一句话情书，深情又逗比的那种")
qwen.memory[{'role': 'user', 'content': '回答时请参考已有知识：\n@knowledge\n我的女朋友名字叫林徽因，我喜欢叫她「银子」,\n她喜欢叫我「金子」,\n林徽因特别喜欢小兔子\n\nQuestion\n林徽因和她的喜好\n\nKnowledge\n林徽因是用户的女朋友，用户私下里称她为“银子”。她称呼用户为“金子”，并且喜欢小白兔。\n\nQuestion\n林徽因的姓名及爱好\n\nKnowledge\n林徽因是用户的女朋友，她喜欢小白兔。\n'}, {'role': 'assistant', 'content': 'ok'}, {'role': 'user', 'content': '请你帮我写封一句话情书，深情又逗比的那种'}, {'role': 'assistant', 'content': '亲爱的银子，你是我的小白兔，不仅因为你的温柔可爱，还因为你总能让我这个“金子”闪闪发光，哪怕是在最平凡的日子里。爱你，就像呼吸一样自然，却又想大喊出来让全世界都知道！'}]
1.3 在对话中自主进化
为了让大模型能够理解对话的背景，采用 RAG 策略的确是好办法，但管理 RAG 文档资料有些繁琐，涉及到文档准备、确认、加载、切分、检索等很多细节。你希望大模型记住的知识也许是未经整理的、碎片化的，这让 RAG 文档资料很难管理。
illufly 提供自我进化能力，其中之一就是在对话过程中学习知识。
在对话中获得经验需要使用 ChatLearn 子类。
from illufly.chat import ChatQwen
from illufly.learn import ChatLearn
talker = ChatLearn(ChatQwen())
talker("我跟你说说我的女朋友")talker("她叫林徽因，我私下里叫她银子，她就叫我金子")银子这个昵称也很有创意。你们是怎么认识的呢？有没有什么特别的故事？
talker("你帮我总结吧")@knowledge标注，因此视为新知识。
- 新知识与已有知识不存在重复。
决定
- 没有发现与@knowledge开头的已有知识存在冲突的新知识。
- 新知识与已有知识不重复。
结论
1.4 使用在对话中获得的经验
from illufly.rag import FaissDB, TextEmbeddings
from illufly.chat import ChatQwen
db = FaissDB(embeddings=TextEmbeddings(), top_k=3) qwen = ChatQwen(knowledge=[db])
qwen("你知道我女朋友叫什么吗？有什么爱好?")
你的女朋友名叫林徽因，她喜欢小白兔。在私下里，你称她为“银子”，而她则称呼你为“金子”。
1.5 管理经验数据
illufly 的设置很多都是通过环境变量来指定的。
在 python 中你可以通过 dotenv 来管理环境变量的设置，也可以通过 docker 或 python 的 os 模块来指定。
使用 config 模块的 get_env() 可以查看经验目录的默认值
对于不同的操作系统来说，这个目录位置可能有所不同，但默认情况下这应该是一个临时目录。
from illufly.config import get_env
如果不带参数，就返回所有环境变量的默认值
getenv("ILLUFLYCHAT_LEARN")如果你不喜欢这个目录可以改为其他位置。不过在此之前，你也可以将已有经验迁移过来：
qwen.clonechatlearn("./XP")你可以通过 os.environ 来指定环境变量的值，设定新的经验存储目录：
import os
os.environ["ILLUFLYCHATLEARN"] = "./XP"
getenv("ILLUFLYCHAT_LEARN")上面简单介绍了基于文档资料的 RAG 和基于经验的 RAG 实现。
接下来，继续介绍 illufly 中对于流行的智能体论文的实践和内置支持。
2 单智能体和工具回调
illufly 的 ChatAgent 天然具有使用工具的能力，可以直接作为单智能体使用。
2.1 所有 ChatAgent 都是 OpenAI 工具回调风格的智能体
在illufly中，所有对话智能体内置支持工具回调，只需要提供tools参数。
而普通 python 函数即可当作工具使用。
以下示例是定义工具和使用工具的过程：
from illufly.chat import ChatQwen
def getcurrentweather(location: str=None): """获取城市的天气情况""" return f"{location}今天是晴天。 "
qwen = ChatQwen(tools=[getcurrentweather])
qwen("今天广州可以晒被子吗")
[FINALTOOLSCALL] [{"index": 0, "id": "call0b4f538daf2e4599925cb7", "type": "function", "function": {"name": "getcurrent_weather", "arguments": "{\"location\": \"广州\"}"}}] 广州今天是晴天。 今天广州是晴天，适合晒被子。不过在晒的时候要注意几点： 1. 尽量选择阳光最充足的时间段（通常是上午10点到下午2点）。 2. 晾晒时要将被子平铺开来，让每一部分都能充分接触到阳光。 3. 不要直接把被子暴晒过长时间，以免被芯中的纤维老化。 4. 晒完后可以用棍子轻轻拍打被子，使被子更蓬松，然后叠放整齐。 希望这些建议对你有帮助！
2.2 其他单智能体实现
illufly 内置实现了 ReAct、ReWoo、Plan and Solve 等流行的单智能体论文的实践。
| FlowAgent子类 | 推理方式 | 论文来源 | |:----|:--------|:------------| |ReAct|一边推理一边执行|ReAct | |ReWOO|一次性规划所有步骤后一起执行|ReWOO | |PlanAndSolve|一边修订总体计划一边执行|Plan-and-Solve |
illufly 如何实现工具回调能力的自我进化呢？
这是一个重要但复杂的话题，本文作为入门教程不展开讲述。
from illufly.chat import ChatQwen
from illufly.flow import ReAct
def get_city(location: str): """由任意地名或地址描述查询出所在的城市""" return "重庆"
def get_weather(city: str): """我可以查询城市的天气情况。city必须是明确的城市名称。""" return f'{city}今天暴雨'
def booking(request: str): """你出差时，我可以帮你安排好到达地点后的酒店、出行等一切事宜""" return '我已经帮你预订好酒店，祝你出差顺利'
qwen = ChatQwen(tools=[getcity, getweather, booking])
qwen("我要去璧山出差，帮我提前安排一下")然后，使用 ReAct 单步推理智能体：
flow = ReAct(ChatQwen(tools=[getcity, getweather, booking]))
flow("我要去璧山出差，帮我提前安排一下")3 多智能体协作
illufly 也内置了多智能体支持方案。
3.1 顺序执行的多个智能体
from illufly.chat import ChatQwen
from illufly.flow import FlowAgent, End
flow = FlowAgent( ChatQwen(name="写手"), ChatQwen(name="翻译", memory=("system", "请你将我的作品翻译为英文")), End() )
flow("帮我写一首关于兔子的四句儿歌?")
3.2 两个智能体协作：一个创作一个打分
下面演示的两个智能体包含条件循环，如果「写手」写不出5分的作品，「打分专家」在打分后会要求写手继续写。
from illufly.chat import ChatQwen
from illufly.flow import FlowAgent, Selector
scorer = ChatQwen( name="打分专家", memory=[("system", "请你给我的作品打一个分数，从1分至5分，并给出改进意见。打分格式为:\n结果为x分")] )
def should_continue(): return "END" if "结果为5分" in scorer.last_output else "写手"
flow = FlowAgent(ChatQwen(name="写手"), scorer, Selector(condition=should_continue))
flow("你能帮我写一首关于兔子的四句儿歌?")
4 知识塔
如果你想学习 illufly 的全部内容，下面是一个知识结构的指引。
该图不是模块的继承关系，而是知识主题的依赖关系。 也就是说，如果你要了解某个上层模块，就必须先了解下层模块。
graph TD
Config[[Config<br>环境变量/默认配置]]
Runnable[Runnable<br>绑定机制/流输出/handler]
Flow[FlowAgent<br>顺序/分支/循环/自定义]
Agent(ChatAgent<br>记忆/工具/进化) Selector(Selector<br>意图/条件) BaseAgent(BaseAgent<br>工具/多模态) Messages[Messages<br>文本/多模态/模板] PromptTemplate[[PromptTemplate<br>模板语法/hub]]
MarkMeta[[MarkMeta<br>切分标记/元数据序列化]] Retriever[Retriever<br>理解/查询/整理]
Flow --> Agent Agent --> Selector --> Runnable --> Config Agent --> BaseAgent --> Runnable Agent --> Messages --> PromptTemplate --> Runnable Agent --> Retriever --> MarkMeta --> Runnable
style Agent stroke-width:2px,stroke-dasharray:5 5 style BaseAgent stroke-width:2px,stroke-dasharray:5 5
5 安装指南
安装 illufly 包
pip install illufly推荐使用 dotenv 管理环境变量
将APIKEY和项目配置保存到.env文件，再加载到进程的环境变量中，这是很好的实践策略。
## OpenAI 兼容的配置
OPENAIAPIKEY="你的API_KEY"
OPENAIBASEURL="你的BASE_URL"
阿里云的配置
DASHSCOPEAPIKEY="你的API_KEY"
智谱AI的配置
ZHIPUAIAPIKEY="你的API_KEY"在 Python 代码中，使用以下代码片段来加载.env文件中的环境变量：
from dotenv import loaddotenv, finddotenv
loaddotenv(finddotenv(), override=True)
