QscQ commited on
Commit
034cfed
·
verified ·
1 Parent(s): ca5c87d

Update docs/function_call_guide_cn.md

Browse files
Files changed (1) hide show
  1. docs/function_call_guide_cn.md +216 -61
docs/function_call_guide_cn.md CHANGED
@@ -6,9 +6,122 @@ MiniMax-M1 模型支持函数调用功能,使模型能够识别何时需要调
6
 
7
  ## 🚀 快速开始
8
 
9
- ### 聊天模板使用
10
 
11
- MiniMax-M1 使用特定的聊天模板格式处理函数调用。聊天模板定义在 `tokenizer_config.json` 中,你可以在代码中通过 template 来进行使用。
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
12
 
13
  ```python
14
  from transformers import AutoTokenizer
@@ -16,21 +129,19 @@ from transformers import AutoTokenizer
16
  def get_default_tools():
17
  return [
18
  {
19
- {
20
- "name": "get_current_weather",
21
- "description": "Get the latest weather for a location",
22
- "parameters": {
23
- "type": "object",
24
- "properties": {
25
- "location": {
26
- "type": "string",
27
- "description": "A certain city, such as Beijing, Shanghai"
28
- }
29
- },
30
- }
31
- "required": ["location"],
32
- "type": "object"
33
  }
 
 
34
  }
35
  ]
36
 
@@ -52,6 +163,27 @@ text = tokenizer.apply_chat_template(
52
  add_generation_prompt=True,
53
  tools=tools
54
  )
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
55
  ```
56
 
57
  ## 🛠️ 函数调用的定义
@@ -100,22 +232,21 @@ text = tokenizer.apply_chat_template(
100
  在模型内部处理时,函数定义会被转换为特殊格式并拼接到输入文本中:
101
 
102
  ```
103
- ]~!b[]~b]system ai_setting=MiniMax AI
104
- MiniMax AI是由上海稀宇科技有限公司(MiniMax)自主研发的AI助理。[e~[
105
- ]~b]system tool_setting=tools
106
  You are provided with these tools:
107
  <tools>
108
  {"name": "search_web", "description": "搜索函数。", "parameters": {"properties": {"query_list": {"description": "进行搜索的关键词,列表元素个数为1。", "items": {"type": "string"}, "type": "array"}, "query_tag": {"description": "query的分类", "items": {"type": "string"}, "type": "array"}}, "required": ["query_list", "query_tag"], "type": "object"}}
109
  </tools>
110
-
111
  If you need to call tools, please respond with <tool_calls></tool_calls> XML tags, and provide tool-name and json-object of arguments, following the format below:
112
  <tool_calls>
113
  {"name": <tool-name>, "arguments": <args-json-object>}
114
  ...
115
- </tool_calls>[e~[
116
- ]~b]user name=用户
117
- OpenAI 和 Gemini 的最近一次发布会都是什么时候?[e~[
118
- ]~b]ai name=MiniMax AI
119
  ```
120
 
121
  ### 模型输出格式
@@ -132,16 +263,15 @@ Okay, I will search for the OpenAI and Gemini latest release.
132
  </tool_calls>
133
  ```
134
 
135
- ## 📥 函数调用结果处理
136
 
137
  ### 解析函数调用
138
 
139
- 您可以使用以下代码解析模型输出的函数调用:
140
 
141
  ```python
142
  import re
143
  import json
144
-
145
  def parse_function_calls(content: str):
146
  """
147
  解析模型输出中的函数调用
@@ -191,23 +321,33 @@ def execute_function_call(function_name: str, arguments: dict):
191
  # 构建函数执行结果
192
  return {
193
  "role": "tool",
194
- "name": function_name,
195
- "content": json.dumps({
196
- "location": location,
197
- "temperature": "25",
198
- "unit": "celsius",
199
- "weather": "晴朗"
200
- }, ensure_ascii=False)
201
- }
 
 
 
 
 
202
  elif function_name == "search_web":
203
  query_list = arguments.get("query_list", [])
204
  query_tag = arguments.get("query_tag", [])
205
  # 模拟搜索结果
206
  return {
207
  "role": "tool",
208
- "name": function_name,
209
- "content": f"搜索关键词: {query_list}, 分类: {query_tag}\n搜索结果: 相关信息已找到"
210
- }
 
 
 
 
 
211
 
212
  return None
213
  ```
@@ -222,46 +362,61 @@ def execute_function_call(function_name: str, arguments: dict):
222
 
223
  ```json
224
  {
225
- "data": [
226
- {
227
- "role": "tool",
228
- "name": "search_web",
229
- "content": "search_result"
230
- }
 
231
  ]
232
  }
233
  ```
234
 
235
  对应如下的模型输入格式:
236
  ```
237
- ]~b]tool name=search_web
238
- search_result[e~[
 
 
239
  ```
240
 
241
-
242
  #### 多个结果
243
- 假如模型同时调用了 `search_web` 和 `get_current_weather` 函数,您可以参考如下格式添加执行结果,`name` 字段为"tools",`content`包含多个结果。
 
244
 
245
  ```json
246
  {
247
- "data": [
248
- {
249
- "role": "tool",
250
- "name": "tools",
251
- "content": "Tool name: search_web\nTool result: test_result1\n\nTool name: get_current_weather\nTool result: test_result2"
252
- }
 
 
 
 
 
 
253
  ]
254
  }
255
  ```
256
 
257
  对应如下的模型输入格式:
258
  ```
259
- ]~b]tool name=tools
260
- Tool name: search_web
261
- Tool result: test_result1
262
-
263
- Tool name: get_current_weather
264
- Tool result: test_result2[e~[
265
  ```
266
 
267
- 虽然我们建议您参考以上格式,但只要返回给模型的输入易于理解,`name` 和 `content` 的具体内容完全由您自主决定。
 
 
 
 
 
 
 
 
6
 
7
  ## 🚀 快速开始
8
 
9
+ ### 使用 vLLM 进行 Function Calls(推荐)
10
 
11
+ 在实际部署过程中,为了支持类似 OpenAI API 的原生 Function Calling(工具调用)能力,MiniMax-M1 模型集成了专属 `tool_call_parser=minimax` 解析器,从而避免对模型输出结果进行额外的正则解析处理。
12
+
13
+ #### 环境准备与重新编译 vLLM
14
+
15
+ 由于该功能尚未正式发布在 PyPI 版本中,需基于源码进行编译。以下为基于 vLLM 官方 Docker 镜像 `vllm/vllm-openai:v0.8.3` 的示例流程:
16
+
17
+ ```bash
18
+ IMAGE=vllm/vllm-openai:v0.8.3
19
+ DOCKER_RUN_CMD="--network=host --privileged --ipc=host --ulimit memlock=-1 --shm-size=32gb --rm --gpus all --ulimit stack=67108864"
20
+
21
+ # 运行 docker
22
+ sudo docker run -it -v $MODEL_DIR:$MODEL_DIR \
23
+ -v $CODE_DIR:$CODE_DIR \
24
+ --name vllm_function_call \
25
+ $DOCKER_RUN_CMD \
26
+ --entrypoint /bin/bash \
27
+ $IMAGE
28
+ ```
29
+
30
+ #### 编译 vLLM 源码
31
+
32
+ 进入容器后,执行以下命令以获取源码并重新安装:
33
+
34
+ ```bash
35
+ cd $CODE_DIR
36
+ git clone https://github.com/vllm-project/vllm.git
37
+ cd vllm
38
+ pip install -e .
39
+ ```
40
+
41
+ #### 启动 vLLM API 服务
42
+
43
+ ```bash
44
+ export SAFETENSORS_FAST_GPU=1
45
+ export VLLM_USE_V1=0
46
+
47
+ python3 -m vllm.entrypoints.openai.api_server \
48
+ --model MiniMax-M1-80k \
49
+ --tensor-parallel-size 8 \
50
+ --trust-remote-code \
51
+ --quantization experts_int8 \
52
+ --enable-auto-tool-choice \
53
+ --tool-call-parser minimax \
54
+ --chat-template vllm/examples/tool_chat_template_minimax_m1.jinja \
55
+ --max_model_len 4096 \
56
+ --dtype bfloat16 \
57
+ --gpu-memory-utilization 0.85
58
+ ```
59
+
60
+ **⚠️ 注意:**
61
+ - `--tool-call-parser minimax` 为关键参数,用于启用 MiniMax-M1 自定义解析器
62
+ - `--enable-auto-tool-choice` 启用自动工具选择
63
+ - `--chat-template` 模板文件需要适配 tool calling 格式
64
+
65
+ #### Function Call 测试脚本示例
66
+
67
+ 以下 Python 脚本基于 OpenAI SDK 实现了一个天气查询函数的调用示例:
68
+
69
+ ```python
70
+ from openai import OpenAI
71
+ import json
72
+
73
+ client = OpenAI(base_url="http://localhost:8000/v1", api_key="dummy")
74
+
75
+ def get_weather(location: str, unit: str):
76
+ return f"Getting the weather for {location} in {unit}..."
77
+
78
+ tool_functions = {"get_weather": get_weather}
79
+
80
+ tools = [{
81
+ "type": "function",
82
+ "function": {
83
+ "name": "get_weather",
84
+ "description": "Get the current weather in a given location",
85
+ "parameters": {
86
+ "type": "object",
87
+ "properties": {
88
+ "location": {"type": "string", "description": "City and state, e.g., 'San Francisco, CA'"},
89
+ "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
90
+ },
91
+ "required": ["location", "unit"]
92
+ }
93
+ }
94
+ }]
95
+
96
+ response = client.chat.completions.create(
97
+ model=client.models.list().data[0].id,
98
+ messages=[{"role": "user", "content": "What's the weather like in San Francisco? use celsius."}],
99
+ tools=tools,
100
+ tool_choice="auto"
101
+ )
102
+
103
+ print(response)
104
+
105
+ tool_call = response.choices[0].message.tool_calls[0].function
106
+ print(f"Function called: {tool_call.name}")
107
+ print(f"Arguments: {tool_call.arguments}")
108
+ print(f"Result: {get_weather(**json.loads(tool_call.arguments))}")
109
+ ```
110
+
111
+ **输出示例:**
112
+ ```
113
+ Function called: get_weather
114
+ Arguments: {"location": "San Francisco, CA", "unit": "celsius"}
115
+ Result: Getting the weather for San Francisco, CA in celsius...
116
+ ```
117
+
118
+ ### 手动解析模型输出
119
+
120
+ 如果您无法使用 vLLM 的内置解析器,或者需要使用其他推理框架(如 transformers、TGI 等),可以使用以下方法手动解析模型的原始输出。这种方法需要您自己解析模型输出的 XML 标签格式。
121
+
122
+ #### 使用 Transformers 的示例
123
+
124
+ 以下是使用 transformers 库的完整示例:
125
 
126
  ```python
127
  from transformers import AutoTokenizer
 
129
  def get_default_tools():
130
  return [
131
  {
132
+ "name": "get_current_weather",
133
+ "description": "Get the latest weather for a location",
134
+ "parameters": {
135
+ "type": "object",
136
+ "properties": {
137
+ "location": {
138
+ "type": "string",
139
+ "description": "A certain city, such as Beijing, Shanghai"
140
+ }
141
+ },
 
 
 
 
142
  }
143
+ "required": ["location"],
144
+ "type": "object"
145
  }
146
  ]
147
 
 
163
  add_generation_prompt=True,
164
  tools=tools
165
  )
166
+
167
+ # 发送请求(这里使用任何推理服务)
168
+ import requests
169
+ payload = {
170
+ "model": "MiniMaxAI/MiniMax-M1-40k",
171
+ "prompt": text,
172
+ "max_tokens": 4000
173
+ }
174
+ response = requests.post(
175
+ "http://localhost:8000/v1/completions",
176
+ headers={"Content-Type": "application/json"},
177
+ json=payload,
178
+ stream=False,
179
+ )
180
+
181
+ # 模型输出需要手动解析
182
+ raw_output = response.json()["choices"][0]["text"]
183
+ print("原始输出:", raw_output)
184
+
185
+ # 使用下面的解析函数处理输出
186
+ function_calls = parse_function_calls(raw_output)
187
  ```
188
 
189
  ## 🛠️ 函数调用的定义
 
232
  在模型内部处理时,函数定义会被转换为特殊格式并拼接到输入文本中:
233
 
234
  ```
235
+ <begin_of_document><beginning_of_sentence>system ai_setting=MiniMax AI
236
+ MiniMax AI是由上海稀宇科技有限公司(MiniMax)自主研发的AI助理。<end_of_sentence>
237
+ <beginning_of_sentence>system tool_setting=tools
238
  You are provided with these tools:
239
  <tools>
240
  {"name": "search_web", "description": "搜索函数。", "parameters": {"properties": {"query_list": {"description": "进行搜索的关键词,列表元素个数为1。", "items": {"type": "string"}, "type": "array"}, "query_tag": {"description": "query的分类", "items": {"type": "string"}, "type": "array"}}, "required": ["query_list", "query_tag"], "type": "object"}}
241
  </tools>
 
242
  If you need to call tools, please respond with <tool_calls></tool_calls> XML tags, and provide tool-name and json-object of arguments, following the format below:
243
  <tool_calls>
244
  {"name": <tool-name>, "arguments": <args-json-object>}
245
  ...
246
+ </tool_calls><end_of_sentence>
247
+ <beginning_of_sentence>user name=用户
248
+ OpenAI 和 Gemini 的最近一次发布会都是什么时候?<end_of_sentence>
249
+ <beginning_of_sentence>ai name=MiniMax AI
250
  ```
251
 
252
  ### 模型输出格式
 
263
  </tool_calls>
264
  ```
265
 
266
+ ## 📥 手动解析函数调用结果
267
 
268
  ### 解析函数调用
269
 
270
+ 当需要手动解析时,您需要解析模型输出的 XML 标签格式:
271
 
272
  ```python
273
  import re
274
  import json
 
275
  def parse_function_calls(content: str):
276
  """
277
  解析模型输出中的函数调用
 
321
  # 构建函数执行结果
322
  return {
323
  "role": "tool",
324
+ "content": [
325
+ {
326
+ "name": function_name,
327
+ "type": "text",
328
+ "text": json.dumps({
329
+ "location": location,
330
+ "temperature": "25",
331
+ "unit": "celsius",
332
+ "weather": "晴朗"
333
+ }, ensure_ascii=False)
334
+ }
335
+ ]
336
+ }
337
  elif function_name == "search_web":
338
  query_list = arguments.get("query_list", [])
339
  query_tag = arguments.get("query_tag", [])
340
  # 模拟搜索结果
341
  return {
342
  "role": "tool",
343
+ "content": [
344
+ {
345
+ "name": function_name,
346
+ "type": "text",
347
+ "text": f"搜索关键词: {query_list}, 分类: {query_tag}\n搜索结果: 相关信息已找到"
348
+ }
349
+ ]
350
+ }
351
 
352
  return None
353
  ```
 
362
 
363
  ```json
364
  {
365
+ "role": "tool",
366
+ "content": [
367
+ {
368
+ "name": "search_web",
369
+ "type": "text",
370
+ "text": "test_result"
371
+ }
372
  ]
373
  }
374
  ```
375
 
376
  对应如下的模型输入格式:
377
  ```
378
+ <beginning_of_sentence>tool name=tools
379
+ tool name: search_web
380
+ tool result: test_result
381
+ <end_of_sentence>
382
  ```
383
 
 
384
  #### 多个结果
385
+
386
+ 假如模型同时调用了 `search_web` 和 `get_current_weather` 函数,您可以参考如下格式添加执行结果,`content`包含多个结果。
387
 
388
  ```json
389
  {
390
+ "role": "tool",
391
+ "content": [
392
+ {
393
+ "name": "search_web",
394
+ "type": "text",
395
+ "text": "test_result1"
396
+ },
397
+ {
398
+ "name": "get_current_weather",
399
+ "type": "text",
400
+ "text": "test_result2"
401
+ }
402
  ]
403
  }
404
  ```
405
 
406
  对应如下的模型输入格式:
407
  ```
408
+ <beginning_of_sentence>tool name=tools
409
+ tool name: search_web
410
+ tool result: test_result1
411
+ tool name: get_current_weather
412
+ tool result: test_result2<end_of_sentence>
 
413
  ```
414
 
415
+ 虽然我们建议您参考以上格式,但只要返回给模型的输入易于理解,`name` 和 `text` 的具体内容完全由您自主决定。
416
+
417
+ ## 📚 参考资料
418
+
419
+ - [MiniMax-M1 模型仓库](https://github.com/MiniMaxAI/MiniMax-M1)
420
+ - [vLLM 项目主页](https://github.com/vllm-project/vllm)
421
+ - [vLLM Function Calling PR](https://github.com/vllm-project/vllm/pull/20297)
422
+ - [OpenAI Python SDK](https://github.com/openai/openai-python)