diff --git a/README_TOOLS.md b/README_TOOLS.md new file mode 100644 index 0000000..f9a5e88 --- /dev/null +++ b/README_TOOLS.md @@ -0,0 +1,86 @@ +# 🛠️小棉工具 +小棉工具(MarshoTools)是一个简单的模块加载器,允许从插件数据目录下的`tools`目录内加载数个工具包与其中定义的函数,以供 AI 模型调用。 +有关 Function Call 的更多信息,请参阅[OpenAI 官方文档](https://platform.openai.com/docs/guides/function-calling)。 + +## ✍️ 编写工具 +### 📁 目录结构 +插件数据目录下的`tools`目录被称作**工具集**,其中可包含数个**工具包**,工具包与 Python 的**包**结构类似,需要在其中包含`__init__.py`文件与`tools.json`定义文件,这些文件将被用于存放以及定义编写的函数。 + +一个工具包的目录结构类似于: +``` +tools/ # 工具集目录 +└── marshoai-example/ # 工具包目录,以包名命名 + └── __init__.py # 工具模块 + └── tools.json # 函数定义文件 +``` +在这个目录树中: +- **工具包目录**是以`marshoai-xxxxx`命名的目录,目录名即为工具包的包名。编写工具时,应尽量采取此命名标准。 +- **工具模块**可包含数个可调用的**异步**函数,可以接受入参,也可以不接受。它们的返回值数据类型应为 AI 模型受支持的类型,一般情况下`str`被大部分模型所支持。 +- **函数定义文件**是让 AI 模型知道如何调用这些函数的关键。 +### 编写函数 +来编写一个简单的函数吧,例如一个获取天气的函数和一个获取时间的函数: +###### **\_\_init\_\_.py** +```python +from datetime import datetime + +async def get_weather(location: str): + return f"{location}的温度是114514℃。" #模拟天气返回信息 + +async def get_current_time(): + current_time = datetime.now().strftime("%Y.%m.%d %H:%M:%S") + time_prompt = f"现在的时间是{current_time}。" + return time_prompt +``` +在这个示例代码中,定义了`get_weather`和`get_current_time`两个函数,其中一个接受`str`类型的地点入参。要让 AI 模型知道这两个函数的存在以及调用的条件和方法,需要编写**函数定义文件**。 +###### **tools.json** +```json +[ + { + "type": "function", + "function": { + "name": "marshoai-example__get_weather", # 函数调用名称 + "description": "查询指定地点的天气。", # 对该函数的描述,需要清楚描述该函数的用途 + "parameters": { # 定义函数的入参 + "type": "object", + "properties": { + "location": { # 此处'location'即为__init__.py定义的入参名 + "type": "string", # 该入参的数据类型 + "description": "城市或县区,比如北京市、杭州市、余杭区等。" # 对该入参的描述,需要清楚描述该入参应传入什么样子的内容 + } + } + }, + "required": [ # 定义该函数的必需入参 + "location" + ] + } + }, + { + "type": "function", + "function": { + "name": "marshoai-example__get_current_time", + "description": "获取现在的时间。", + "parameters": {} # 该函数不需要入参,故此处为空 + } + } +] +``` +在这个文件中定义了两个已经编写好的函数,该定义文件将被输入到 AI 模型中,来让 AI 模型知道这些函数的存在与调用方法。 +**函数调用名称**的命名方式比较特别。以获取天气的函数为例,它的函数调用名称`marshoai-example__get_weather`包含三个信息: +- 前面的**marshoai-example**即为该函数所在工具包的**包名**。 +- 后面的**get_weather**是这个函数在代码里的名称。 +- 中间的两个下划线是用于分割这两个信息的分隔符。 + +使用这种命名方式,是为了兼容更多的 OpenAI 标准格式 API。因此,在给工具包和函数取名时,不要使用带有两个下划线的名称。 +### 测试函数 +在编写完工具后,启动 Bot,Nonebot 的日志应当会输出工具包的加载信息。 +以下是测试示例: +``` +> marsho 深圳天气怎么样 +深圳的天气显示温度是114514°C,真是不可思议呢!这一定是个误报吧~(≧▽≦) 希望你那里有个好天气哦! +> marsho 分别告诉我下北泽,杭州,苏州的天气 +下北泽、杭州和苏州的天气都显示温度为114514°C呢!这么奇怪的温度,一定是个误报吧~(≧▽≦) + +如果要查看真实的天气情况,建议查看专业天气预报哦~ +> marsho 现在几点了 +现在的时间是2024年11月23日,21点05分哦~(*^ω^) 你准备做些什么呢? +```