Runs_大模型服务平台百炼-阿里云帮助中心

本文档主要基于当前Dashscope的run 类所具备的各类可被开发者使用的API 文档。

函数名	类型
Create run	创建一个run 类，用于运行thread
Create thread and run	创建一个thread并直接运行
list run	创建某个thread的多个run
list run step	创建某个run的多个run step
retrieve run	检索 run 实例
retrieve run step	检索 run step
modify run	修改某个run 实例
Submit tool outputs to run	将tools运行的中间结果传递给run，并让run从暂停状态转换为继续运行状态

1. Create run

1.1 代码示例

curl --location 'https://dashscope.aliyuncs.com/api/v1/threads/thread_cc2a3e9d-436b-482b-91c5-377e0f376506/runs' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>' \
--data '{
    "assistant_id": "asst_46e95014-ccac-435d-b884-c97ac44a94d9",
    "metadata": {}
}'

1.2 输入参数解释

输入参数名字	输入参数的描述	参数类型	是否必须
thread id	所需要运行的thread id	str	是
assistant id	所需要运行的assistant id	str	是
model	所需要调用的model名字。如果在此传入，会替换掉assistant中定义的model	str	否
instructions	替换assistant中定义的instruction	str	否
additional instruction	额外增加一部分instruction至原有instruction 末尾。	str	否
tools	替换assistant中定义的tool 列表	str	否
metadata	其他相关参数说明	str	否

1.3 输出参数解释

{
    "id": "run_3de634fa-75d4-4370-adcf-92ba2a60c396",
    "object": "thread.run",
    "created_at": 1711517598169,
    "thread_id": "thread_cc2a3e9d-436b-482b-91c5-377e0f376506",
    "assistant_id": "asst_46e95014-ccac-435d-b884-c97ac44a94d9",
    "status": "in_progress",
    "model": "qwen-max",
    "instructions": "你是一个智能小助手，你可以根据用户的需求去调用不同的工具，进而给出回答。请酌情使用工具。",
    "tools": [
        {
            "type": "search"
        },
        {
            "type": "wanx"
        }
    ],
    "file_ids": [],
    "metadata": {},
    "request_id": "225292ff-9843-95d4-8591-b1377c33e2be"
}

输出run类，并包含除了用户输入以外参数的其他额外字段：

id ：run id
thread id：运行的run内包含的thread id
assistant id：所运行的assistant id
request_id ：请求id

2. Create thread and run

2.1 代码示例

curl --location 'https://dashscope.aliyuncs.com/api/v1/threads/runs' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>' \
--data '{
    "assistant_id": "asst_ce66cfa8-b2f8-4e4c-8e17-2c335145be42",
    "thread": {
        "messages": [
            {
                "role": "user",
                "content": "西安天气是什么"
            }
        ]
    }
}'

2.2 输入参数解释

输入参数名字	输入参数的描述	参数类型	是否必须
thread id	所需要运行的thread id	str	是
assistant id	所需要运行的assistant id	str	是
thread	所需要运行的thread信息	dict	是

2.3 输出参数解释

{
    "id": "run_99935dbd-e731-4bad-b450-60d9d6bf9a44",
    "object": "thread.run",
    "created_at": 1711519089921,
    "thread_id": "thread_9157dfad-71fd-4add-b7a9-1afa452d2d67",
    "assistant_id": "asst_ce66cfa8-b2f8-4e4c-8e17-2c335145be42",
    "status": "in_progress",
    "model": "qwen-max",
    "instructions": "你是一个智能小助手，你可以根据用户的需求去调用不同的工具，进而给出回答。请酌情使用工具。",
    "tools": [
        {
            "type": "wanx"
        },
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA"
                        },
                        "unit": {
                            "type": "string",
                            "enum": [
                                "celsius",
                                "fahrenheit"
                            ]
                        }
                    },
                    "required": [
                        "location"
                    ]
                }
            }
        }
    ],
    "file_ids": [],
    "metadata": {},
    "request_id": "191ecdaa-7ef6-9e29-8572-4f89be05bc6c"
}

输出run类，并包含除了用户输入以外参数的其他额外字段：

id ：run id
thread id：运行的run内包含的thread id
assistant id：所运行的assistant id
request_id ：请求id

3. list run

3.1 代码示例

curl --location 'https://dashscope.aliyuncs.com/api/v1/threads/thread_cc2a3e9d-436b-482b-91c5-377e0f376506/runs?limit=20&order=asc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>'

3.2 输入参数解释

输入参数名字	输入参数的描述	参数类型	是否必须
thread id	run list 所隶属的thread id	str	是
limit	创建message的数量	int	否
order	按照创建时间升序或降序	str	否（默认为“desc")

3.3 输出参数解释

{
    "object": "list",
    "data": [
        {
            "id": "run_3de634fa-75d4-4370-adcf-92ba2a60c396",
            "object": "thread.run",
            "created_at": 1711517598169,
            "thread_id": "thread_cc2a3e9d-436b-482b-91c5-377e0f376506",
            "assistant_id": "asst_46e95014-ccac-435d-b884-c97ac44a94d9",
            "status": "completed",
            "required_action": {},
            "last_error": {},
            "expires_at": 0,
            "started_at": 0,
            "cancelled_at": 0,
            "failed_at": 0,
            "completed_at": 0,
            "model": "qwen-max",
            "instructions": "你是一个智能小助手，你可以根据用户的需求去调用不同的工具，进而给出回答。请酌情使用工具。",
            "tools": [
                {
                    "type": "search"
                },
                {
                    "type": "wanx"
                }
            ],
            "file_ids": [],
            "metadata": {},
            "usage": {
                "prompt_tokens": 66,
                "completion_tokens": 9,
                "total_tokens": 75
            }
        }
    ],
    "first_id": "run_3de634fa-75d4-4370-adcf-92ba2a60c396",
    "last_id": "run_3de634fa-75d4-4370-adcf-92ba2a60c396",
    "has_more": false,
    "request_id": "ff3d2aea-555c-9825-80ca-24029a636641"
}

输出List run类，并包含除了用户输入以外参数的其他额外字段：

多个run 组成的列表

4. list run step

4.1 代码示例

用于创建某个run的多个run step

curl --location 'https://dashscope.aliyuncs.com/api/v1/threads/thread_cc2a3e9d-436b-482b-91c5-377e0f376506/runs/run_3de634fa-75d4-4370-adcf-92ba2a60c396/steps?limit=20&order=asc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>'

4.2 输入参数解释

输入参数名字	输入参数的描述	参数类型	是否必须
thread id	run 所传入的thread id	str	是
run id	创建的run step所隶属的run id	str	是
limit	创建message file的数量	int	否
order	按照创建时间升序或降序	str	否（默认为“desc")

4.3 输出参数解释

{
    "object": "list",
    "data": [
        {
            "id": "step_4db180b5-d44a-4b12-9390-4307c6cb87a5",
            "object": "thread.run.step",
            "created_at": 1711517599333,
            "assistant_id": "asst_46e95014-ccac-435d-b884-c97ac44a94d9",
            "thread_id": "thread_cc2a3e9d-436b-482b-91c5-377e0f376506",
            "run_id": "run_3de634fa-75d4-4370-adcf-92ba2a60c396",
            "type": "message_creation",
            "status": "completed",
            "step_details": {
                "type": "message_creation",
                "message_creation": {
                    "message_id": "message_75c67937-a829-4741-ae83-6839cae81269"
                }
            },
            "last_error": {
                "code": "",
                "message": ""
            },
            "expires_at": 0,
            "started_at": 0,
            "cancelled_at": -1,
            "failed_at": -1,
            "completed_at": -1,
            "metadata": {},
            "usage": {}
        }
    ],
    "first_id": "step_4db180b5-d44a-4b12-9390-4307c6cb87a5",
    "last_id": "step_4db180b5-d44a-4b12-9390-4307c6cb87a5",
    "has_more": false,
    "request_id": "df979778-7c6a-9f45-b7da-758ae00d1e19"
}

输出list run step 类，并包含除了用户输入以外参数的其他额外字段：

list run step 类
request_id ：请求id

5. retrieve run

5.1 代码示例

curl --location 'https://dashscope.aliyuncs.com/api/v1/threads/thread_cc2a3e9d-436b-482b-91c5-377e0f376506/runs/run_3de634fa-75d4-4370-adcf-92ba2a60c396' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>'

5.2 输入参数解释

输入参数名字	输入参数的描述	参数类型	是否必须
thread id	待检索的run id 所传入的thread id	str	是
run_id	待检索的run_id	str	是

5.3 输出参数解释

{
    "id": "run_3de634fa-75d4-4370-adcf-92ba2a60c396",
    "object": "thread.run",
    "created_at": 1711517598169,
    "thread_id": "thread_cc2a3e9d-436b-482b-91c5-377e0f376506",
    "assistant_id": "asst_46e95014-ccac-435d-b884-c97ac44a94d9",
    "status": "completed",
    "required_action": {},
    "last_error": {},
    "expires_at": 0,
    "started_at": 0,
    "cancelled_at": 0,
    "failed_at": 0,
    "completed_at": 0,
    "model": "qwen-max",
    "instructions": "你是一个智能小助手，你可以根据用户的需求去调用不同的工具，进而给出回答。请酌情使用工具。",
    "tools": [
        {
            "type": "search"
        },
        {
            "type": "wanx"
        }
    ],
    "file_ids": [],
    "metadata": {},
    "usage": {
        "prompt_tokens": 66,
        "completion_tokens": 9,
        "total_tokens": 75
    },
    "request_id": "05c5f4ea-5e6b-9901-9849-7a0943a0db43"
}

输出检索到的message类，并包含除了用户输入以外参数的其他额外字段：

id ：run id
thread id：运行的run内包含的thread id
assistant id：所运行的assistant id
request_id ：请求id

6. retrieve run step

6.1 代码示例

curl --location 'https://dashscope.aliyuncs.com/api/v1/threads/thread_cc2a3e9d-436b-482b-91c5-377e0f376506/runs/run_3de634fa-75d4-4370-adcf-92ba2a60c396/steps/step_4db180b5-d44a-4b12-9390-4307c6cb87a5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>'

6.2 输入参数解释

输入参数名字	输入参数的描述	参数类型	是否必须
thread id	待检索的run 所传入的thread id	str	是
run_id	待检索的run step的所属run id	str	是
step_id	待检索的run step id	str	是
*	其他可选的输入参数	str	否

6.3 输出参数解释

{
    "id": "step_4db180b5-d44a-4b12-9390-4307c6cb87a5",
    "object": "thread.run.step",
    "created_at": 1711517599333,
    "assistant_id": "asst_46e95014-ccac-435d-b884-c97ac44a94d9",
    "thread_id": "thread_cc2a3e9d-436b-482b-91c5-377e0f376506",
    "run_id": "run_3de634fa-75d4-4370-adcf-92ba2a60c396",
    "type": "message_creation",
    "status": "completed",
    "step_details": {
        "type": "message_creation",
        "message_creation": {
            "message_id": "message_75c67937-a829-4741-ae83-6839cae81269"
        }
    },
    "last_error": {
        "code": "",
        "message": ""
    },
    "expires_at": 0,
    "started_at": 0,
    "cancelled_at": -1,
    "failed_at": -1,
    "completed_at": -1,
    "metadata": {},
    "usage": {},
    "request_id": "938643a3-d56d-966f-8c17-2cb09772475e"
}

输出检索到的run step类，并包含除了用户输入以外参数的其他额外字段：

id ：run step id
request_id ：请求id

7. modify run

7.1 代码示例

curl --location 'https://dashscope.aliyuncs.com/api/v1/threads/thread_cc2a3e9d-436b-482b-91c5-377e0f376506/runs/run_3de634fa-75d4-4370-adcf-92ba2a60c396' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>' \
--data '{
    "metadata": {
        "user": "abc123"
    }
}'

7.2 输入参数解释

输入参数名字	输入参数的描述	参数类型	是否必须
thread_id	待修改的thread_id	str	是
run_id	待修改的run_id	str	是
*	其他可选的输入参数	str	否

7.3 输出参数解释

{
    "id": "run_3de634fa-75d4-4370-adcf-92ba2a60c396",
    "object": "thread.run",
    "created_at": 1711517598169,
    "thread_id": "thread_cc2a3e9d-436b-482b-91c5-377e0f376506",
    "assistant_id": "asst_46e95014-ccac-435d-b884-c97ac44a94d9",
    "status": "completed",
    "required_action": {},
    "last_error": {},
    "expires_at": 0,
    "started_at": 0,
    "cancelled_at": 0,
    "failed_at": 0,
    "completed_at": 0,
    "model": "qwen-max",
    "instructions": "你是一个智能小助手，你可以根据用户的需求去调用不同的工具，进而给出回答。请酌情使用工具。",
    "tools": [
        {
            "type": "search"
        },
        {
            "type": "wanx"
        }
    ],
    "file_ids": [],
    "metadata": {
        "user": "abc123"
    },
    "usage": {
        "prompt_tokens": 66,
        "completion_tokens": 9,
        "total_tokens": 75
    },
    "request_id": "bb6a5c5c-146f-95b8-bafa-e6c467e4f2d3"
}

输出修改后run类，并包含除了用户输入以外参数的其他额外字段：

id ：run_id
request_id ：请求id

8. Submit tool outputs to run

在使用Function call过程中，会需要把中间function运行结果返回给run，并将run的状态从“require_action" 切换回正常状态。此时，“required_action.type” 的值为“submit_tool_outputs”。

8.1 代码示例

curl --location 'https://dashscope.aliyuncs.com/api/v1/threads/thread_9157dfad-71fd-4add-b7a9-1afa452d2d67/runs/run_99935dbd-e731-4bad-b450-60d9d6bf9a44/submit_tool_outputs' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR-DASHSCOPE-API-KEY>' \
--data '{
    "tool_outputs": [
      {
        "tool_call_id": "",
        "output": "rain"
      }
    ]
  }'

8.2 输入参数解释

输入参数名字	输入参数的描述	参数类型	是否必须
thread_id	待修改的thread_id	str	是
run_id	待修改的run_id	str	是
tool_outputs	一个tools外部调用的输出结果的列表	array	是

8.3 输出参数解释

{
    "id": "run_99935dbd-e731-4bad-b450-60d9d6bf9a44",
    "object": "thread.run",
    "created_at": 1711519089921,
    "thread_id": "thread_9157dfad-71fd-4add-b7a9-1afa452d2d67",
    "assistant_id": "asst_ce66cfa8-b2f8-4e4c-8e17-2c335145be42",
    "status": "in_progress",
    "required_action": {
        "type": "submit_tool_outputs",
        "submit_tool_outputs": {
            "tool_calls": [
                {
                    "function": {
                        "name": "get_current_weather",
                        "arguments": "{\"location\": \"西安\"}"
                    },
                    "id": "",
                    "type": "function"
                }
            ]
        }
    },
    "last_error": {},
    "expires_at": 0,
    "started_at": 0,
    "cancelled_at": 0,
    "failed_at": 0,
    "completed_at": 0,
    "model": "qwen-max",
    "instructions": "你是一个智能小助手，你可以根据用户的需求去调用不同的工具，进而给出回答。请酌情使用工具。",
    "tools": [
        {
            "type": "wanx"
        },
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "Get the current weather in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city and state, e.g. San Francisco, CA"
                        },
                        "unit": {
                            "type": "string",
                            "enum": [
                                "celsius",
                                "fahrenheit"
                            ]
                        }
                    },
                    "required": [
                        "location"
                    ]
                }
            }
        }
    ],
    "file_ids": [],
    "metadata": {},
    "usage": null,
    "request_id": "792c29a2-e771-9840-9d99-df4f892badd0"
}

输出修改后run类，并包含除了用户输入以外参数的其他额外字段：

id ：run_id
request_id ：请求id