限制返回格式功能（glyph）

POSThttps://api.minimax.chat/v1/text/chatcompletion_pro

该功能可以帮助用户强制要求模型按照配置的固定格式返回内容，当前支持配置的格式详见下表。

4.3.2 请求体(request)参数

如需使用该功能，则需要在使用基础功能参数的同时，额外添加以下参数。

参数位置	参数	语义	取值	备注
body	reply_constraints.glyph	限制的返回格式配置	dict
reply_constraints.glyph.type	使用什么模板功能当前仅支持1、raw2、json_value	string
	reply_constraints.glyph.raw_glyph	需要限制的格式要求，使用 glpyh 语法	string	详见下文 glyph 语法说明章节
	reply_constraints.glyph.json_properties	需要限制的格式要求，使用 dict描述json语法	dict	包括properties，properties包括参数及每个参数的类型type.包含三种基础类型：string boolean number以及对象类型和数组类型。object对象类型支持生成嵌套数据，array数组类型支持生成一组指定类型的数据。可以参考下面的json value的请求示例
	glyph.json_object.json_properties	需要限制的格式要求，使用 dict描述json语法	dict	dict 的 key 由用户定义，描述需要生成的东西； value 是一个嵌套的 property，定义生成数据的结构和类型。可以参考下面的json value的请求示例
	glyph.json_object.json_properties[].type		stringbooleannumberobject array	必传字段，包含三种基础类型：string boolean number两种嵌套类型：object array
	glyph.json_object.json_properties[].properties	描述需要生成的数据，可输入多个字段	dict	定义生成数据的类型和结构比如，想生成名字和年龄，key-value 示例如下：`{ "glyph": { "type":"json_value", "json_properties" :{ "name": { "type": "string", }, "age": { "type": "number", } } } }`
	glyph.json_object.json_properties.property_list	有序的properties	List	当需要生成数据的key和输入顺序一致时，需要使用 property_list`{ "glyph": { "type":"json_value", "property_list" :[ { "properties": { "name": { "type": "string", } } }, { "properties": { "age": { "type": "number", } } } ] } }`
	glyph.json_object.json_properties.properties[].Items	当glyph.json_object.json_properties[].type=array时用来定义数组中生成内容的类型	dict	例：比如要生成一组名字示例如下`{ "glyph": { "type":"json_value", "json_properties" :{ "name": { "type":"array", "items": { "type": "string" } } } } }`

glyph 语法说明

raw_glpyh

在 {{ }} 之外的部分，模型输出会完全一致

在 {{ }} 之中的部分，模型会按照语法要求输出

举例：

如果 glyph 为 "《蒙娜丽莎》是{{gen 'name'}}的画作"
模型可能会输出 "蒙娜丽莎是列奥纳多·达·芬奇的画作"

模型不会输出 "列奥纳多·达·芬奇画了《蒙娜丽莎》"



如果 glyph 为 "西柚的类型为{{select 'type' options=['家电','其他']}}"
模型可能会输出 "西柚的类型为其他"

模型不会输出 "西柚的类型为水果"

详细语法如下：

语句	语句说明	支持参数	参数说明	参数类型	备注
gen	生成指令，提示文本生成	stop	模型停止生成需匹配的内容	正则表达式	1.仅在该段{{ }}范围生效；2.可与 pattern、temperature、blank_max_tokens同时生效
pattern	生成内容需匹配的内容，生成内容需有明确的结束标志	正则表达式	1.仅在该段{{ }}范围生效；2.需在正则表达式中给出结束标志，比如数量上限，或者结束标志等；3.可与 pattern、temperature、blank_max_tokens同时生效；


temperature	Sampling temperature，控制采样输出的随机性。较高的值将获得更加随机的输出	float （0, 1]	1.仅在该段{{ }}范围生效；2.可与 stop、pattern、blank_max_tokens同时生效
blank_max_tokens	gen语句生成内容最大长度限制，优先级高于stop和pattern，低于全局的max_tokens	int	1.仅在该段{{ }}范围生效；2.可与stop、 pattern、temperature同时生效
select	选择指令，限定模型输出的范围	options	选择生成文本的范围。必填	list[str]	1.仅在该段{{ }}范围生效；2.可与 use_regex同时生效
use_regex	是否使用正则表达式的方式匹配options中的内容	bool	1.仅在该段{{ }}范围生效；2.可与 options同时生效

4.3.3 raw_glyph 请求示例

{
    "bot_setting": [ 
        {
            "bot_name": "MM智能助理",
            "content": "MM智能助理是一款由MiniMax自研的，没有调用其他产品的接口的大型语言模型。MiniMax是一家中国科技公司，一直致力于进行大模型相关的研究。"
        }
    ],
    "messages": [ 
        {
            "sender_type": "USER",
            "sender_name": "小明",
            "text": "请用英语帮我翻译下面这句话：我是谁"
        }
    ],
    "reply_constraints": { 
        "sender_type": "BOT",
        "sender_name": "MM智能助理",
        "glyph": {
            "type": "raw",
            "raw_glyph": "这句话的翻译是：{{gen 'content'}}"
        }
    },
    "model": "abab5.5-chat", 
    "tokens_to_generate": 1034,
    "temperature": 0.01,
    "top_p": 0.95
}

4.3.4 json_value请求示例

单层请求示例

{
    "model": "abab5.5-chat",
    "tokens_to_generate": 1024,
    "temperature": 0.9,
    "top_p": 0.95,
    "stream": false,
    "beam_width": 1,
    "reply_constraints": {
        "sender_type": "BOT",
        "sender_name": "MM智能助理",
        "glyph": {
            "json_properties": {
                "name": {
                    "type": "string"
                },
                "age": {
                    "type": "number"
                },
                "is_student": {
                    "type": "boolean"
                },
                "is_boy": {
                    "type": "boolean"
                },
                "courses": {
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "string"
                        },
                        "score": {
                            "type": "number"
                        }
                    }
                }
            },
            "type": "json_value"
        }
    },
    "sample_messages": [],
    "plugins": [],
    "messages": [
        {
            "sender_type": "USER",
            "sender_name": "用户",
            "text": "帮我提取以下信息的关键词：我叫月无双，来自太阳大学，今年18岁，刚刚考完《斗气化翼》课程，得了99.99分"
        }
    ],
    "bot_setting": [
        {
            "bot_name": "MM智能助理",
            "content": "MM智能助理是一款由MiniMax自研的，没有调用其他产品的接口的大型语言模型。MiniMax是一家中国科技公司，一直致力于进行大模型相关的研究。"
        }
    ],
    "trace_id":"!231312"
}

嵌套请求示例

{
    "model": "abab5.5-chat",
    "tokens_to_generate": 1024,
    "temperature": 0.9,
    "top_p": 0.95,
    "stream": false,
    "beam_width": 1,
    "reply_constraints": {
        "sender_type": "BOT",
        "sender_name": "MM智能助理",
        "glyph": {
            "type": "json_value",
            "json_properties": {
                "student": {
                    "type": "object",
                    "property_list": [
                        {
                            "properties": {
                                "name": {
                                    "type": "string"
                                }
                            }
                        },
                        {
                            "properties": {
                                "mark": {
                                    "type": "string"
                                }
                            }
                        },
                        {
                            "properties": {
                                "mark1": {
                                    "type": "string"
                                }
                            }
                        },
                        {
                            "properties": {
                                "age": {
                                    "type": "boolean"
                                }
                            }
                        },
                        {
                            "properties": {
                                "comments": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    ]
                }
            }
        }
    },
    "sample_messages": [],
    "plugins": [],
    "messages": [
        {
            "sender_type": "USER",
            "sender_name": "用户",
            "text": "帮我提取以下信息的关键词，最后生成一系列积极的评语：我叫月无双，来自太阳大学，今年18岁，刚刚考完《斗气化翼》课程，得了99.99分。"
        }
    ],
    "bot_setting": [
        {
            "bot_name": "MM智能助理",
            "content": "MM智能助理是一款由MiniMax自研的，没有调用其他产品的接口的大型语言模型。MiniMax是一家中国科技公司，一直致力于进行大模型相关的研究。"
        }
    ],
    "trace_id": "!231312"
}

4.3.5 返回(response)参数

在返回基础功能参数的同时，额外返回以下参数

参数位置	参数	语义	取值	备注
body	glyph_result	glyph语法的返回结果	dict

4.3.6 返回示例

raw_glyph 返回示例

{
    "created":1699522169,
    "model":"abab5.5-chat",
    "reply":"这句话的翻译是：\"Who am I?\"",
    "choices":[
        {
            "finish_reason":"stop",
            "glyph_result":{
                "content":"\"Who am I?\""
            },
            "messages":[
                {
                    "sender_type":"BOT",
                    "sender_name":"MM智能助理",
                    "text":"这句话的翻译是：\"Who am I?\""
                 }
             ]
         }
    ],
    "usage":{
            "total_tokens":169
    },
    "input_sensitive":false,
    "output_sensitive":false,
    "id":"019bd9785cbe54eabc8e9beeea608552",
    "base_resp":{
        "status_code":0,
        "status_msg":""
    }
}

json_value返回示例

需要注意的是当您在使用type=array类型时，如若对话服务输出的内容较长直至超出所设置的tokens_to_generate的数值，那么将会表现出array生成到一半即会被截断的结果。

如果您出现以上所描述的情况，可以通过以下操作进行解决：调整tokens_to_generate的上限数值，并且同步修改优化prompt，让模型感知到array需要多长。同时应尽量避免使用“说几个”、“给一些”等不确定数量的说法。

单层返回示例

{
    "created": 1695026998,
    "model": "abab5.5-chat",
    "reply": "{\n  \"name\": \"月无双\",\n  \"is_student\": true,\n  \"courses\":   {\n    \"name\": \"斗气化翼\",\n    \"score\": 99.99\n  },\n  \"age\": 18\n}",
    "choices": [
        {
            "finish_reason": "stop",
            "messages": [
                {
                    "sender_type": "BOT",
                    "sender_name": "MM智能助理",
                    "text": "{\n  \"name\": \"月无双\",\n  \"is_student\": true,\n  \"courses\":   {\n    \"name\": \"斗气化翼\",\n    \"score\": 99.99\n  },\n  \"age\": 18\n}"
                }
            ]
        }
    ],
    "usage": {
        "total_tokens": 350
    },
    "input_sensitive": false,
    "output_sensitive": false,
    "id": "0157422df0a266482950e56badee8bfc",
    "base_resp": {
        "status_code": 0,
        "status_msg": ""
    }
}

嵌套返回示例

{
    "model": "abab5.5-chat",
    "tokens_to_generate": 1024,
    "temperature": 0.9,
    "top_p": 0.95,
    "stream": false,
    "beam_width": 1,
    "reply_constraints": {
        "sender_type": "BOT",
        "sender_name": "MM智能助理",
        "glyph": {
            "type": "json_value",
            "json_properties": {
                "student": {
                    "type": "object",
                    "property_list": [
                        {
                            "properties": {
                                "name": {
                                    "type": "string"
                                }
                            }
                        },
                        {
                            "properties": {
                                "mark": {
                                    "type": "string"
                                }
                            }
                        },
                        {
                            "properties": {
                                "mark1": {
                                    "type": "string"
                                }
                            }
                        },
                        {
                            "properties": {
                                "age": {
                                    "type": "boolean"
                                }
                            }
                        },
                        {
                            "properties": {
                                "comments": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    ]
                }
            }
        }
    },
    "sample_messages": [],
    "plugins": [],
    "messages": [
        {
            "sender_type": "USER",
            "sender_name": "用户",
            "text": "帮我提取以下信息的关键词，最后生成一系列积极的评语：我叫月无双，来自太阳大学，今年18岁，刚刚考完《斗气化翼》课程，得了99.99分。"
        }
    ],
    "bot_setting": [
        {
            "bot_name": "MM智能助理",
            "content": "MM智能助理是一款由MiniMax自研的，没有调用其他产品的接口的大型语言模型。MiniMax是一家中国科技公司，一直致力于进行大模型相关的研究。"
        }
    ],
    "trace_id": "!231312"
}

请求参数

Header 参数

Authorization

string

可选

Content-Type

string

可选

bot_setting

array [object {2}]

必需

bot_name

string

可选

content

string

可选

messages

array [object {3}]

必需

sender_type

string

可选

sender_name

string

可选

text

string

可选

reply_constraints

object

必需

sender_type

string

必需

sender_name

string

必需

glyph

object

限制的返回格式配置

必需

model

string

必需

tokens_to_generate

integer

必需

temperature

number

必需

top_p

number

必需

{
  "bot_setting": [
    {
      "bot_name": "MM智能助理",
      "content": "MM智能助理是一款由MiniMax自研的，没有调用其他产品的接口的大型语言模型。MiniMax是一家中国科技公司，一直致力于进行大模型相关的研究。"
    }
  ],
  "messages": [
    {
      "sender_type": "USER",
      "sender_name": "小明",
      "text": "请用英语帮我翻译下面这句话：我是谁"
    }
  ],
  "reply_constraints": {
    "sender_type": "BOT",
    "sender_name": "MM智能助理",
    "glyph": {
      "type": "raw",
      "raw_glyph": "这句话的翻译是：{{gen 'content'}}"
    }
  },
  "model": "abab5.5-chat",
  "tokens_to_generate": 1034,
  "temperature": 0.01,
  "top_p": 0.95
}

示例代码

返回响应

成功(200)

HTTP 状态码: 200

内容格式: JSONapplication/json

created

integer

必需

model

string

必需

string

必需

choices

array [object {3}]

必需

finish_reason

string

可选

glyph_result

object

可选

messages

array [object {3}]

可选

usage

object

必需

total_tokens

integer

必需

input_sensitive

boolean

必需

output_sensitive

boolean

必需

string

必需

base_resp

object

必需

status_code

integer

必需

status_msg

string

必需

{
  "created": 1699522169,
  "model": "abab5.5-chat",
  "reply": "这句话的翻译是：\"Who am I?\"",
  "choices": [
    {
      "finish_reason": "stop",
      "glyph_result": {
        "content": "\"Who am I?\""
      },
      "messages": [
        {
          "sender_type": "BOT",
          "sender_name": "MM智能助理",
          "text": "这句话的翻译是：\"Who am I?\""
        }
      ]
    }
  ],
  "usage": {
    "total_tokens": 169
  },
  "input_sensitive": false,
  "output_sensitive": false,
  "id": "019bd9785cbe54eabc8e9beeea608552",
  "base_resp": {
    "status_code": 0,
    "status_msg": ""
  }
}

最后修改时间： 1 年前