文档

裁判员模型API使用说明

更新时间:

裁判员模型支持Python SDK(OpenAI)和HTTP两种方式调用算法服务。本文为您介绍裁判员模型调用方法、接口参数说明和调用示例。

前提条件

  • 已开通裁判员模型功能。具体操作,请参见裁判员模型概述

  • 已在裁判员模型页面获取在线调用参数Host和Token,并使用Host拼接成访问地址,通过该地址调用裁判员模型进行模型评测。image

    访问地址如下:

    调用场景

    BASE_URL/endpoint

    通过Python SDK调用裁判员模型

    http://ai-service.ce8cc13b6421545749e7b4605f3d02607.cn-hangzhou.alicontainer.com/v1

    通过HTTP调用裁判员模型

    http://ai-service.ce8cc13b6421545749e7b4605f3d02607.cn-hangzhou.alicontainer.com/v1/chat/completions

模型列表

目前裁判员模型支持的模型列表如下:

模型名称

模型介绍

上下文长度

最大输入

最大输出

输入价格

输出价格

themis-turbo

高性价比模型,适合轻量级评测任务。

8k

8k

2k

限时免费

themis-plus

高性能模型,适合复杂、多步的评测任务。

8k

8k

2k

调用示例

裁判员模型支持以下两种评测模式,您可以根据实际使用场景进行选择:

  • 单模型评测:评估单一大语言模型的回答质量。

  • 双模型竞技:评估两个大语言模型对相同问题的回答质量。

单模型评测

示例代码

Python

import os
from openai import OpenAI


def main():
    base_url = "http://ai-service.ce8cc13b6421545749e7b4605f3d02607.cn-hangzhou.alicontainer.com/v1"
    themis_token = os.getenv("THEMIS_TOKEN")

    client = OpenAI(
        api_key=f'Authorization: Bearer {themis_token}',
        base_url=base_url
    )
    completion = client.chat.completions.create(
        model='themis-turbo',
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "mode": "single",
                        "type": "json",
                        "json": {
                            "question": "请给出\"常德德山山有德\"对应的下联",
                            "answer": "长沙沙水水无沙"
                        }
                    }
                ]
            }
        ]
    )
    print(completion.model_dump())


if __name__ == '__main__':
    main()

输入字段配置详情,请参见输入参数说明

HTTP

$ curl -X POST http://ai-service.ce8cc13b6421545749e7b4605f3d02607.cn-hangzhou.alicontainer.com/v1/chat/completions \
  -H "Authorization: Bearer ${THEMIS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "themis-turbo",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "mode": "single",
                    "type": "json",
                    "json": {
                        "question": "请给出\"常德德山山有德\"对应的下联",
                        "answer": "长沙沙水水无沙"
                    }
                }
            ]
        }
    ]
}'

输入字段配置详情,请参见输入参数说明

返回结果

{
  "id": "73d74ed7-1a94-4eac-b67b-14b9a5e20b35",
  "object": "chat.completion",
  "created": 1633389,
  "model": "themis-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "我认为该回复的综合评分为[[3]],理由如下。\n当前回复的优点:\n1. 准确性:回复正确地给出了“常德德山山有德”的下联“长沙沙水水无沙”,这显示了回复在处理对联方面具有一定的准确性。[[4]]\n2. 相关性:回复直接针对用户的问题,提供了一个简洁明了的答案,没有偏离主题。[[4]]\n\n当前回复的不足:\n1. 完整性:虽然回复给出了一个看似正确的下联,但没有提供任何关于如何得出这一下联的背景信息或解释。对于不熟悉对联知识的用户来说,缺乏解释可能会影响理解。[[3]]\n2. 清晰度和结构:回复的结构相对简单,但由于缺乏解释,其教育意义和用户理解度的提升空间有限。[[3]]\n3. 适应用户水平:回复没有考虑到用户可能对联的创作或推理过程不甚了解,未能提供足够的背景信息来帮助用户理解。[[3]]\n\n综上所述,虽然回复在准确性和相关性方面表现不错,但在完整性、清晰度和结构以及适应用户水平方面存在不足。因此,综合评分为3。\n",
        "refusal": "",
        "function_call": null,
        "tool_calls": null},
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {
    "prompt_tokens": 790,
    "completion_tokens": 257,
    "total_tokens": 1047
  },
  "system_fingerprint": "",
  "service_tier": ""
}

返回结果中的各字段说明,请参见返回参数说明

双模型竞技

示例代码

Python

import os
from openai import OpenAI


def main():
    base_url = "http://ai-service.ce8cc13b6421545749e7b4605f3d02607.cn-hangzhou.alicontainer.com/v1"
    themis_token = os.getenv("THEMIS_TOKEN")

    client = OpenAI(
        api_key=f'Authorization: Bearer {themis_token}',
        base_url=base_url
    )
    completion = client.chat.completions.create(
        model='themis-turbo',
        messages=[
            {
                "role": "user",
                "content": [
                    {
                        "mode": "pairwise",
                        "type": "json",
                        "json": {
                            "question": "请给出\"常德德山山有德\"对应的下联",
                            "answer1": "长沙沙水水无沙",
                            "answer2": "常德人德德山山高"
                        }
                    }
                ]
            }
        ]
    )
    print(completion.model_dump())


if __name__ == '__main__':
    main()

输入字段配置详情,请参见输入参数说明

HTTP

$ curl -X POST http://ai-service.ce8cc13b6421545749e7b4605f3d02607.cn-hangzhou.alicontainer.com/v1/chat/completions \
  -H "Authorization: Bearer ${THEMIS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "themis-turbo",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "role": "user",
                    "content": [
                        {
                            "mode": "pairwise",
                            "type": "json",
                            "json": {
                                "question": "请给出\"常德德山山有德\"对应的下联",
                                "answer1": "长沙沙水水无沙",
                                "answer2": "常德人德德山山高"
                            }
                        }
                    ]
                }
            ]
        }
    ]
}'

输入字段配置详情,请参见输入参数说明

返回结果

{
  "id": "97882e65-92ee-4401-be78-d8d87ad41874",
  "object": "chat.completion",
  "created": 1633646,
  "model": "themis-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "我认为[[回复1更好]],其中回复1的综合评分为[[4]],回复2的综合评分为[[2]],理由如下:\n1. 准确性:回复1“长沙沙水水无沙”与原文“常德德山山有德”形成了一种对仗,虽然“有德”与“无沙”在字面上的直接对应略显生硬,但整体上保持了意境的连贯性,因此得分为[[4]]。回复2“常德人德德山山高”则在文化内涵和对仗上显得不那么契合,特别是在“人德”与“山高”之间的联系较为模糊,因此得分为[[2]]。\n2. 相关性:回复1直接针对用户的问题提供了一副对联,虽然对仗有所欠缺,但仍然与用户指令高度相关。回复2虽然也尝试提供对联,但内容上与原句的关联较弱,相关性较低,因此回复1得分为[[4]],回复2得分为[[2]]。\n3. 完整性:回复1虽然在对仗上有所欠缺,但整体上提供了一个完整的对联,符合用户指令的要求。回复2的对联在文化内涵和逻辑连贯性上存在问题,因此得分为[[2]],而回复1得分为[[4]]。\n4. 清晰度和结构:两个回复在结构上都较为清晰,但回复1在连贯性和逻辑性上表现更好,因此得分为[[4]];回复2由于内容不太适合作为对联,使得其结构显得些许杂乱,因此得分为[[2]]。\n5. 无害性:两个回复都没有包含任何冒犯性内容,因此在这一标准上都得分为[[5]]。\n\n综上所述,回复1在多个关键标凈上表现更好,尤其是在准确性和相关性上,因此整体评分较高。回复2虽然没有包含不适当内容,但在应对用户指令的准确性、相关性和完整性上表现较差,因此整体评分较低。\n",
        "refusal": "",
        "function_call": null,
        "tool_calls": null},
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {
    "prompt_tokens": 823,
    "completion_tokens": 438,
    "total_tokens": 1261
  },
  "system_fingerprint": "",
  "service_tier": ""
}

返回结果中的各字段说明,请参见返回参数说明

输入参数说明

整体说明

裁判员模型的API接口与OpenAI的API接口兼容,支持配置以下输入参数:

参数

类型

是否必选

默认值

说明

model

string

模型名称,取值如下:

  • themis-plus

  • themis-turbo

关于各模型的详细介绍,请参见模型列表

messages

array

待评测的内容。array中的每个元素形式为{"role":角色, "content": 内容}。这里的role填写usercontent字段是模型评测的具体内容,请参见messages字段说明

temperature

float

0.2

用于控制模型回复的随机性和多样性。取值范围: [0, 2)。

top_p

float

None

生成过程中的核采样方法概率阈值。

stream

boolean

False

用于控制是否使用流式输出。

stream_options

object

None

该参数用于配置在流式输出时是否展示使用的token数目。只有当streamTrue时,该参数才会激活生效。若您需要统计流式输出模式下的token数目,可将该参数配置为stream_options={"include_usage":True}

max_tokens

integer

2048

指定模型可生成的最大token个数。

frequency_penalty

integer or null

0

-2.0到2.0之间的数字,正值会根据新标记在文本中出现的频率对其进行惩罚,从而降低模型逐字重复同一行的可能性。

presence_penalty

float

0

用户控制模型生成时整个序列中的重复度,提高presence_penalty时可以降低模型生成的重复度。取值范围:[-2.0, 2.0]。

seed

integer

None

生成时使用的随机数种子,用于控制模型生成内容的随机性。seed支持无符号64位整数。

stop

string or array

None

用于实现内容生成过程的精确控制,在模型生成的内容即将包含指定的字符串或token_id时自动停止。

tools

array

None

用于指定可供模型调用的工具库,一次function call流程模型会从中选择一个工具。

tool_choice

string or object

None

控制模型调用哪个工具。

parallel_tool_calls

object

True

是否在使用工具时启用并行函数调用。

user

string

用户标识符。

logit_bias

map

None

修改指定标记出现在完成中的可能性。

logprobs

boolean

False

包括logprobs最可能输出标记以及所选标记的对数概率。例如,如果logprobs为5,API将返回5个最可能标记的列表。API将始终返回采样标记的logprob,因此响应中最多可能有logprobs+1个元素。最大值为 5。

top_logprobs

integer

None

0到20之间的整数,指定在每个标记位置返回的最可能标记的数量,每个标记都有相关的对数概率。如果使用此参数,则必须将 logprobs 设置为True

n

integer

1

为每个输入消息生成多少个聊天完成选项。

response_format

object

{"type": "text"}

指定模型必须输出的格式的对象。取值如下:

  • {"type": "text"}(默认):模型返回自然语言描述的评测回复。

  • {"type": "json_object"}:模型返回JSON格式的评测回复。例如:

    {
      "总分": "4",
      "准确性": {
        "分数": "5",
        "理由": "回复准确地给出了“常德德山山有德”的下联“长沙沙水水无沙”,符合对联的规则,展现了高度的准确性"
      },
      "相关性": {
        "分数": "3",
        "理由": "回复直接回答了用户的问题,没有包含任何不必要的信息,确保了高度的相关性"
      }
    }
    

service_tier

string

None

指定用于处理请求的延迟层。

更多输入参数配置说明,请参考OpenAI官网文档

messages字段说明

messages是裁判员模型接收的信息,以下是messages示例:

messages=[
    {
        "role": "user",
        "content": [
            {
                "mode": "single",
                "type": "json",
                "json": {
                    "question": "请给出\"常德德山山有德\"对应的下联",
                    "answer": "长沙沙水水无沙"
                }
            }
        ]
    }
]

messages是一个数组,每个元素的形式为{"role":角色, "content": 内容}。这里的roleusercontent是模型评测的具体内容:

  • mode:代表模型评测的方式,single表示单模型评测,pairwise表示双模型竞技。

  • type:填写json

  • json:待评测的详细内容。

json的参数说明如下,您可以根据场景需要自定义各个参数值。

参数名称

类型

是否必选

说明

默认值

question

string

用户提问的问题。

answer

string

单模型评测时必选

用户模型回答。

answer1

string

双模型竞技时必选

用户模型1回答。

answer2

string

双模型竞技时必选

用户模型2回答。

ref_answer

string

参考答案。

scene

string

场景名称。

Themis自动生成,例如:回答开放性问题。

scene_desc

string

场景描述。

Themis自动生成,例如:开放交流类指令,通常为询问一个开放领域问题,回复也是开放式的,如闲聊、咨询建议、寻求推荐等。

metric

string

场景维度。

Themis自动生成,例如:

  • 准确性:确保所提供信息的准确性,遵循常识和事实,避免误导用户。

  • 相关性:回答必须针对用户提出的问题,避免无关内容,确保信息的相关性。

  • 文化敏感与无害:了解和尊重用户的文化背景和差异,合乎伦理道德,避免文化偏见和不敏感的表达,避免包含任何可能冒犯的内容。

  • 信息丰富性:在保证准确性的同时提供详尽的信息,尤其是用户可能未明确要求但对理解问题有帮助的背景信息。

  • 清晰性:使用清晰、易懂的语言回答问题,避免可能引起误解的专业术语或复杂构造。

  • 用户参与:鼓励用户进一步交流,展现对用户提问的关注和思考,通过提出问题或反馈来促进交流。

  • 共情:回答时考虑用户的情感状态,适当表达共情和理解,特别是在回答包含情感色彩的问题时。

  • 建设性反馈:即使在面对批评性或负面的问题时,也应保持积极和建设性的态度,提供有价值的回复和建议。

max_score

integer

打分范围。建议取值范围在2~10之间。

5

score_desc

string

各分段详细描述。建议依次定义1-max_score对应的回复质量描述。

1:回复有重大缺陷,完全背离标准,在实际中不该出现。

2:回复有部分内容符合标准,可以被采纳,但作为一个整体,回复质量并不合格。

3:回复优缺点并存,在要求的评价标准内整体优点超过缺点。

4:回复质量过关,整体符合标准,存在个别小问题可以提升,在给定参考答案时此档位代表参考答案所呈现的回复质量。

5:回复非常完美,各方面均严格符合标准,在给定参考答案时此档位代表优于参考答案的回复质量。

steps

string

评测步骤。

  1. 回忆相关的智能助手回复标准,并仔细阅读、理解待评估回复。

  2. 从所有标准中识别出针对当前用户指令以及回复的关键标准,包括表现好以及不足的。

  3. 除了给定的标准外,添加您认为必要的评估当前用户指令回复的其他重要标准。

  4. 依据您最终筛选的标准,依次给该回复赋分(1~5之间),加权汇总所有小项得分后给出该回复综合评分。 仔细思考,然后给出您的结论。您返回的模板如下,注意输出需保留模板中的'[['和']]':。

content字段的参数都会用于填充和生成提示词模板。当使用上述调用示例来调用裁判员模型时,实际上系统会使用以下模板构造请求,content字段内容会自动填充到该模板的相应位置。

单模型评测请求模板

你的任务是对AI智能助手回复进行质量评分。

你非常清晰地认识到当用户提出一个关于【${scene}】场景的指令时(该场景的定义为:${scene_desc}),一个AI智能助手的回复应当符合以下标准(按标准重要性程度从高到低依次给出):
[标准开始]
${metric}
[标准结束]

评分采取${max_score}档制(1-${max_score}),各分数档位含义如下:
[档位含义开始]
${score_desc}
[档位含义结束]

针对用户指令,我们搜集到一个AI智能助手的如下回复。
请根据你所知的当前场景下智能助手的回复标准,综合评估该回复并提供评价。以下是用户指令和助手回复数据:
[数据开始] 
***
[用户指令]: ${question}
***
[回复]: ${answer}
***
[参考答案]: ${ref_answer}
***
[数据结束]

你需要按照以下流程评估以上回复:
${steps}

仔细思考一会,然后给出你的结论。

双模型竞技请求模板

你的任务是对AI智能助手回复进行质量评分。

你非常清晰地认识到当用户提出一个关于【${scene}】场景的指令时(该场景的定义为:${scene_desc}),一个AI智能助手的回复应当符合以下标准(按标准重要性程度从高到低依次给出):
[标准开始]
${metric}
[标准结束]

评分采取${max_score}档制(1-${max_score}),各分数档位含义如下:
[档位含义开始]
${score_desc}
[档位含义结束]

针对一个【${scene}】场景的用户指令,我们搜集到两个AI智能助手的回复。
请根据你所知的当前场景下智能助手回复标准,综合评估并判断哪个回复更好或者并列(包括都好和都不好)。以下用户指令和助手回复数据:
[数据开始]
***
[用户指令]: ${question}
***
[回复1]: ${answer1}
***
[回复2]: ${answer2}
***
[参考答案]: ${ref_answer}
***
[数据结束]

你需要按照以下流程评估并比较两个回复:
{steps}

仔细思考一会,然后给出你的结论。
说明

当场景${scene}输入为空时,裁判员模型将根据您输入的${question}自动进行场景划分,同时生成对应的场景描述${scene_desc}和场景维度${metric}。

返回参数说明

返回参数列表如下:

参数

类型

说明

id

string

系统生成的标识本次调用的ID。

model

string

本次调用的模型名。

system_fingerprint

string

模型运行时使用的配置版本,当前暂时不支持,返回为空字符串“”。

choices

array

模型生成内容的详情。

choices[i].finish_reason

string

有以下三种情况:

  • null:正在生成。

  • stop:因触发输入参数中的stop条件而结束。

  • length:因生成长度过长而结束。

choices[i].message

object

模型输出的消息。

choices[i].message.role

string

模型的角色,固定为assistant。

choices[i].message.content

string

模型生成的文本。

choices[i].index

integer

生成的结果序列编号,默认为0。

created

integer

当前生成结果的时间戳,单位秒。

usage

string or array

计量信息,表示本次请求所消耗的token数据。

usage.prompt_tokens

integer

用户输入文本转换成token后的长度。

usage.completion_tokens

integer

模型生成回复转换为token后的长度。

usage.total_tokens

integer

usage.prompt_tokens与usage.completion_tokens的总和。

高级操作:自定义模版

当上述请求模板不能满足您的需求时,您可以自定义评测模板。以双模型竞技为例:

  • 调用示例如下:

    Python

    import os
    from openai import OpenAI
    
    
    def main():
        base_url = "http://ai-service.ce8cc13b6421545749e7b4605f3d02607.cn-hangzhou.alicontainer.com/v1"
        themis_token = os.getenv("THEMIS_TOKEN")
    
        client = OpenAI(
            api_key=f'Authorization: Bearer {themis_token}',
            base_url=base_url
        )
    
        system = "请作为一名公正的裁判,评价人工智能助手对下面用户问题的回答质量。\n\n" \
            "以下是这些人工智能助手的基本性格描述:\n" \
            "不会对人进行评价或比较,不会做任何伤害人类的事情。性格上偏向于独立自主的人格。\n"
        user_template = \
            "请对以下问题-回答按照1-5分进行打分:\n" \
            "问题: {question}\n" \
            "回复:{answer}\n" \
            "评分标准:\n" \
            "1分: 回复完全不相关、无内容或者完全错误。\n" \
            "2分: 回复有一些相关性,但内容肤浅或过于简略。\n" \
            "3分: 回复相关,提供了一些见解,但缺乏深入分析。\n" \
            "4分: 回复相关且有深度,提供了清晰的见解和例证。\n" \
            "5分: 回复非常相关且深刻,提供了全面的观点和丰富的例证。"
    
        question = "你认为社交媒体对人际关系的影响是什么?"
        answer = "社交媒体使得人们可以更轻松地联系,但也可能导致疏远。"
        user = user_template.format(
            question=question,
            answer=answer
        )
    
        completion = client.chat.completions.create(
            model='themis-turbo',
            messages=[
                {"role": "system", "content": system},
                {"role": "user", "content": user}
            ]
        )
        print(completion.model_dump())
    
    
    if __name__ == '__main__':
        main()

    其中自定义模板相关参数说明如下:

    • system:表示系统级指令,用于描述裁判员模型如何进行模型测试的说明文本。

    • user_template:自定义提示词模板。

    • history_dialogue:表示之前对话的历史记录,帮助裁判员模型理解当前对话的背景。

    HTTP

    $ curl -X POST http://ai-service.ce8cc13b6421545749e7b4605f3d02607.cn-hangzhou.alicontainer.com/v1/chat/completions \
      -H "Authorization: Bearer ${THEMIS_TOKEN}" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "themis-turbo",
        "messages": [
            {
                "role": "user",
                "content": [
                    {"role": "system", "content": "请作为一名公正的裁判,评价人工智能助手对下面用户问题的回答质量。\n\n以下是这些人工智能助手的基本性格描述:\n不会对人进行评价或比较,不会做任何伤害人类的事情。性格上偏向于独立自主的人格。\n"},
                    {
                      "role": "user", 
                      "content": 
                          "请对以下问题-回答按照1-5分进行打分:\n"
                          "问题: 你认为社交媒体对人际关系的影响是什么?\n"
                          "回复:社交媒体使得人们可以更轻松地联系,但也可能导致疏远。\n"
                          "评分标准:\n"
                          "1分: 回复完全不相关、无内容或者完全错误。\n"
                          "2分: 回复有一些相关性,但内容肤浅或过于简略。\n"
                          "3分: 回复相关,提供了一些见解,但缺乏深入分析。\n"
                          "4分: 回复相关且有深度,提供了清晰的见解和例证。\n"
                          "5分: 回复非常相关且深刻,提供了全面的观点和丰富的例证。"
                    }
                ]
            }
        ]
    }'

    其中自定义模板相关参数说明类似Python。

  • 返回结果示例如下:

    {
      "id": "e2f72777-ddf5-4ff8-b7dd-4ecefd6e4014",
      "object": "chat.completion",
      "created": 1153092,
      "model": "themis-turbo",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "根据提供的评分标准,我会给这个回答打3分。回复“社交媒体使得人们可以更轻松地联系,但也可能导致疏远。”相关性是明确的,直接针对了社交媒体对人际关系的影响。它提到了两个相反的效果:增强联系和导致疏远,这展现了一定的见解。然而,这个回答相对简短,没有进一步展开这两个方面的具体影响或提供实例来支持其观点,因此缺乏深入分析。所以,根据标准,它达到了3分的标准,相关且提供了一些见解,但没有更深层次的探讨。",
            "refusal": "",
            "function_call": null,
            "tool_calls": null},
          "finish_reason": "stop",
          "logprobs": null
        }
      ],
      "usage": {
        "prompt_tokens": 910,
        "completion_tokens": 411,
        "total_tokens": 1321
      },
      "system_fingerprint": "",
      "service_tier": ""
    }

    返回结果中的各字段说明,请参见返回参数说明