.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "build_tutorial/structured_output.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_build_tutorial_structured_output.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_build_tutorial_structured_output.py:


.. _structured-output:

结构化输出
==========================

如下图所示，AgentScope 支持以下两种结构化输出方式：

- 工具 API：构造一个函数，其输入参数是所需要的结构化数据的字段，然后要求大模型调用该函数，从而获得结构化数据
- 文本解析：调用大模型 API 获得纯文本数据，然后本地从纯文本中解析出结构化数据

.. image:: https://img.alicdn.com/imgextra/i4/O1CN01TLx5qg1tcmx3cKCNN_!!6000000005923-55-tps-661-391.svg
   :width: 100%
   :alt: 两种不同结构化输出方式

两种方式的优缺点如下：

.. list-table::
    :header-rows: 1

    * - 方式
      - 优点
      - 缺点
    * - 工具 API
      - 1. 模型 **自主** 决定何时调用该函数/产生结构化输出，能够很好与 ReAct 算法结合
        2. 数据解析发生在大模型 API 提供方，本地开发难度低
        3. 支持基于 JSON Schema 的复杂约束条件
      - 需要支持工具调用的大模型 API
    * - 文本解析
      - 1. 简单易用
        2. 可以根据模型能力、所需结构化数据的不同，调整格式和解析方法
      - 1. 依赖模型能力，可能一直无法产生符合要求的结构化数据
        2. 模型 **被动** 产生结构化数据，由开发者决定何时提示大模型产生结构化数据


下面我们详细介绍 AgentScope 如何支持两种不同的解析方式。

工具 API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

工具 API 方式将工具调用和结构化输出结合在一起，例如我们需要 `"thought"`，`"choice"`，`"number"`
三个字段，那么我们可以构建如下的函数

.. GENERATED FROM PYTHON SOURCE LINES 45-59

.. code-block:: Python


    from typing import Literal
    from pydantic import BaseModel, Field
    import json


    def generate_response(
        thought: str,
        choice: Literal["apple", "banana"],
        number: int,
    ) -> None:
        pass









.. GENERATED FROM PYTHON SOURCE LINES 60-65

这里函数签名起到了提供约束条件的作用，模型在正确调用该函数时，我们就可以获得对应的结构化数据。

在了解基本思路后，进一步考虑到一些复杂的约束条件无法使用 Python 的类型注解来表达，
在 AgentScope 中，我们支持通过 Pydantic 的 `BaseModel` 的子类来定义复杂的约束条件。
例如下面的两个类

.. GENERATED FROM PYTHON SOURCE LINES 65-89

.. code-block:: Python



    class Model1(BaseModel):
        name: str = Field(
            min_length=0,
            max_length=20,
            description="姓名",
        )
        description: str = Field(
            min_length=0,
            max_length=200,
            description="简短的介绍",
        )
        age: int = Field(
            ge=0,
            le=100,
            description="年龄",
        )


    class Model2(BaseModel):
        choice: Literal["apple", "banana"] = Field(description="你的选择")









.. GENERATED FROM PYTHON SOURCE LINES 90-95

AgentScope 中的 `ReActAgentV2` 会将 `BaseModel` 子类的 JSON Schema 和一个名
为 `generate_response` 函数的 schema 结合在一起，生成一个新的 schema，在模型调用
该函数的时候，可以利用该函数的 Schema 来约束模型的输出。

例如下面我们展示如何使用 `ReActAgentV2` 实现 ReAct 算法和结构化输出的结合

.. GENERATED FROM PYTHON SOURCE LINES 96-123

.. code-block:: Python


    from agentscope.agents import ReActAgentV2
    from agentscope.service import ServiceToolkit
    from agentscope.message import Msg
    import agentscope

    agentscope.init(
        model_configs={
            "config_name": "my_config",
            "model_type": "dashscope_chat",
            "model_name": "qwen-max",
        },
    )

    toolkit = ServiceToolkit()

    agent = ReActAgentV2(
        name="Friday",
        model_config_name="my_config",
        service_toolkit=toolkit,
    )

    msg1 = Msg("user", "介绍下爱因斯坦", "user")
    res_msg = agent(msg1, structured_model=Model1)

    print("结构化输出的内容: ", res_msg.metadata)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Friday: [
        {
            "type": "tool_use",
            "id": "call_5cfc236d08034deca6540a",
            "name": "generate_response",
            "input": {
                "response": "阿尔伯特·爱因斯坦（Albert Einstein, 1879-1955）是一位理论物理学家，他最著名的是发展了相对论，并因此获得了1921年的诺贝尔物理学奖。他的质能方程E=mc²是现代物理学中最知名的公式之一。爱因斯坦对光电效应的研究也为量子理论的发展做出了贡献。",
                "name": "阿尔伯特·爱因斯坦",
                "description": "著名的理论物理学家，相对论的创始人",
                "age": 76
            }
        }
    ]
    system: Execute function generate_response:
    Success
    Friday: 阿尔伯特·爱因斯坦（Albert Einstein, 1879-1955）是一位理论物理学家，他最著名的是发展了相对论，并因此获得了1921年的诺贝尔物理学奖。他的质能方程E=mc²是现代物理学中最知名的公式之一。爱因斯坦对光电效应的研究也为量子理论的发展做出了贡献。
    结构化输出的内容:  {'name': '阿尔伯特·爱因斯坦', 'description': '著名的理论物理学家，相对论的创始人', 'age': 76}




.. GENERATED FROM PYTHON SOURCE LINES 124-125

可以通过切换不同的 `structured_model` 来实现不同的结构化输出

.. GENERATED FROM PYTHON SOURCE LINES 125-131

.. code-block:: Python


    msg2 = Msg("user", "选择一种水果", "user")
    res_msg = agent(msg2, structured_model=Model2)

    print("结构化输出的内容: ", res_msg.metadata)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Friday: [
        {
            "type": "tool_use",
            "id": "call_22c03b21aca74e0a80d69b",
            "name": "generate_response",
            "input": {
                "response": "这里有两种水果供您选择，苹果和香蕉。您想要哪一种呢？",
                "choice": "apple"
            }
        }
    ]
    system: Execute function generate_response:
    Success
    Friday: 这里有两种水果供您选择，苹果和香蕉。您想要哪一种呢？
    结构化输出的内容:  {'choice': 'apple'}




.. GENERATED FROM PYTHON SOURCE LINES 132-134

为了观察 `ReActAgentV2` 中如何动态的构造函数的 schema，这里我们去掉一个清理结构化输出设置的
hook 函数，从而能够打印出对应的加工后的函数 schema

.. GENERATED FROM PYTHON SOURCE LINES 134-149

.. code-block:: Python


    # 清空记忆
    agent.memory.clear()
    # 去掉清理结构化输出的 hook 函数
    agent.remove_hook("post_reply", "as_clear_structured_output")

    # 观察当前目标函数的 schema
    print(
        json.dumps(
            toolkit.json_schemas[agent._finish_function],
            indent=4,
            ensure_ascii=False,
        ),
    )





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    {
        "type": "function",
        "function": {
            "name": "generate_response",
            "parameters": {
                "properties": {
                    "response": {
                        "description": "The response to the user.",
                        "type": "string"
                    }
                },
                "required": [
                    "response"
                ],
                "type": "object"
            },
            "description": "Generate a response. You must call this function to interact with\n\nothers (e.g., users)."
        }
    }




.. GENERATED FROM PYTHON SOURCE LINES 150-151

现在我们调用一次智能体，然后观察目标函数的 schema 变化情况

.. GENERATED FROM PYTHON SOURCE LINES 151-162

.. code-block:: Python


    res_msg = agent(msg1, structured_model=Model1)

    print(
        json.dumps(
            toolkit.json_schemas[agent._finish_function],
            indent=4,
            ensure_ascii=False,
        ),
    )





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Friday: [
        {
            "type": "tool_use",
            "id": "call_bbda181843734c85b3873c",
            "name": "generate_response",
            "input": {
                "response": "阿尔伯特·爱因斯坦（Albert Einstein, 1879-1955）是一位德裔瑞士籍美国理论物理学家，他最著名的贡献是相对论。爱因斯坦提出了光电效应的理论解释，并因此获得了1921年的诺贝尔物理学奖。他的质能方程E=mc²成为了核能和原子弹开发的基础。爱因斯坦不仅在科学上有所建树，还是一个和平主义者和社会活动家。",
                "name": "Albert Einstein",
                "description": "著名理论物理学家，相对论提出者",
                "age": 76
            }
        }
    ]
    system: Execute function generate_response:
    Success
    Friday: 阿尔伯特·爱因斯坦（Albert Einstein, 1879-1955）是一位德裔瑞士籍美国理论物理学家，他最著名的贡献是相对论。爱因斯坦提出了光电效应的理论解释，并因此获得了1921年的诺贝尔物理学奖。他的质能方程E=mc²成为了核能和原子弹开发的基础。爱因斯坦不仅在科学上有所建树，还是一个和平主义者和社会活动家。
    {
        "type": "function",
        "function": {
            "name": "generate_response",
            "parameters": {
                "properties": {
                    "response": {
                        "description": "The response to the user.",
                        "type": "string"
                    },
                    "name": {
                        "description": "姓名",
                        "maxLength": 20,
                        "minLength": 0,
                        "type": "string"
                    },
                    "description": {
                        "description": "简短的介绍",
                        "maxLength": 200,
                        "minLength": 0,
                        "type": "string"
                    },
                    "age": {
                        "description": "年龄",
                        "maximum": 100,
                        "minimum": 0,
                        "type": "integer"
                    }
                },
                "required": [
                    "response",
                    "name",
                    "description",
                    "age"
                ],
                "type": "object"
            },
            "description": "Generate a response. You must call this function to interact with\n\nothers (e.g., users)."
        }
    }




.. GENERATED FROM PYTHON SOURCE LINES 163-181

这里我们可以看出，`generate_response` 函数的 schema 已经与 `Model1` 类的 schema 结合在了一起，
因此，当大模型调用该工具的时候，也就产生了对应的结构化数据。

.. tip:: 更多实现细节可以参考 `ReActAgentV2` 的 `源码`_

.. _源码: https://github.com/modelscope/agentscope/blob/main/src/agentscope/agents/_react_agent_v2.py

文本解析
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

AgentScope 中的 `parsers` 模块提供了多种不同的解析器类，开发者可以根据所需结构化数据的不同选用合适的解析器。

以 Markdown 格式为例，我们展示如何构建一个简单的智能体，并使用 `MarkdownJsonDictParser` 类从文本中解析出字典类型的结构化数据。

构建解析器
-------------------

`MarkdownJsonDictParser` 要求输入的文本将结构化数据包裹在 Markdown 的代码快中，以`\`\`\``作为开头和结尾，并从中解析出对应的字典数据。

.. GENERATED FROM PYTHON SOURCE LINES 181-192

.. code-block:: Python


    from agentscope.models import ModelResponse
    from agentscope.parsers import MarkdownJsonDictParser


    parser = MarkdownJsonDictParser(
        content_hint='{"thought": "你的想法", "speak": "你对用户说的话"}',
        required_keys=["thought", "speak"],
    )









.. GENERATED FROM PYTHON SOURCE LINES 193-194

解析器将根据你的输入生成一个格式说明。你可以在提示中使用 `format_instruction` 属性来指导 LLM 生成所需的输出。

.. GENERATED FROM PYTHON SOURCE LINES 194-197

.. code-block:: Python


    print(parser.format_instruction)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    Respond a JSON dictionary in a markdown's fenced code block as follows:
    ```json
    {"thought": "你的想法", "speak": "你对用户说的话"}
    ```




.. GENERATED FROM PYTHON SOURCE LINES 198-202

解析输出
-------------------
当从 LLM 接收到输出时，使用 `parse` 方法来提取结构化数据。
它接收一个 `agentscope.models.ModelResponse` 对象作为输入，解析 `text` 字段的值，并在 `parsed` 字段中返回解析后的字典。

.. GENERATED FROM PYTHON SOURCE LINES 202-219

.. code-block:: Python


    dummy_response = ModelResponse(
        text="""```json
    {
        "thought": "我应该向用户打招呼",
        "speak": "嗨!我能为您做些什么?"
    }
    ```""",
    )

    print(f"解析前parsed字段: {dummy_response.parsed}")

    parsed_response = parser.parse(dummy_response)

    print(f"解析后parsed字段: {parsed_response.parsed}")
    print(f"parsed字段类型: {type(parsed_response.parsed)}")





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    解析前parsed字段: None
    解析后parsed字段: {'thought': '我应该向用户打招呼', 'speak': '嗨!我能为您做些什么?'}
    parsed字段类型: <class 'dict'>




.. GENERATED FROM PYTHON SOURCE LINES 220-225

错误处理
-------------------
如果LLM的输出与预期格式不匹配，解析器将抛出一个包含详细信息的错误。
开发者可以将错误信息反馈给 LLM，引导其生成正确格式的输出。


.. GENERATED FROM PYTHON SOURCE LINES 225-239

.. code-block:: Python


    error_response = ModelResponse(
        text="""```json
    {
        "thought": "我应该向用户打招呼"
    }
    ```""",
    )

    try:
        parsed_response = parser.parse(error_response)
    except Exception as e:
        print(e)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    RequiredFieldNotFoundError: Missing required field speak in the JSON dictionary object.




.. GENERATED FROM PYTHON SOURCE LINES 240-248

进阶用法
-------------------
复杂结构化输出
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
要求 LLM 直接生成 JSON 字典可能具有挑战性，特别是当 JSON 内容很复杂时（例如代码片段、嵌套结构）。
在这种情况下，你可以使用更高级的解析器来指导 LLM 生成所需的输出。
这里是一个更复杂的解析器示例，可以处理代码片段。


.. GENERATED FROM PYTHON SOURCE LINES 248-267

.. code-block:: Python


    from agentscope.parsers import RegexTaggedContentParser

    parser = RegexTaggedContentParser(
        format_instruction="""按以下格式作答:
    <thought>你的想法</thought>
    <number>这里放一个随机数字</number>
    <code>你的python代码</code>
    """,
        try_parse_json=True,  # 会尝试将每个键值解析为JSON对象，如果失败则保留为字符串
        required_keys=[  # 解析字典中的必需键
            "thought",
            "number",
            "code",
        ],
    )

    print(parser.format_instruction)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    按以下格式作答:
    <thought>你的想法</thought>
    <number>这里放一个随机数字</number>
    <code>你的python代码</code>





.. GENERATED FROM PYTHON SOURCE LINES 268-272

`RegexTaggedContentParser` 支持使用正则表达式匹配文本中的标记内容并返回解析后的字典。

.. note:: `RegexTaggedContentParser` 的解析输出是一个字典，因此 key 必须唯一。
 可以通过设置 `tagged_content_pattern` 参数来更改正则表达式模式。

.. GENERATED FROM PYTHON SOURCE LINES 272-290

.. code-block:: Python


    import json

    dummy_response = ModelResponse(
        text="""<thought>打印当前日期</thought>
    <number>42</number>
    <code>import datetime
    print(datetime.datetime.now())
    </code>
    """,
    )

    parsed_response = parser.parse(dummy_response)

    print("解析响应的类型: ", type(parsed_response.parsed))
    print("number的类型: ", type(parsed_response.parsed["number"]))
    print(json.dumps(parsed_response.parsed, indent=4, ensure_ascii=False))





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    解析响应的类型:  <class 'dict'>
    number的类型:  <class 'int'>
    {
        "thought": "打印当前日期",
        "number": 42,
        "code": "import datetime\nprint(datetime.datetime.now())\n"
    }




.. GENERATED FROM PYTHON SOURCE LINES 291-315

自动后处理
^^^^^^^^^^^^^^^^^^^^

在解析后的字典中，不同的键可能需要不同的后处理步骤。
例如，在狼人杀游戏中，LLM 扮演预言家的角色，输出应该包含以下键值:

- `thought`: 预言家的想法
- `speak`: 预言家的发言
- `use_ability`: 一个布尔值，表示预言家是否应该使用其能力

在这种情况下，`thought` 和 `speak` 内容应该存储在智能体的记忆中，以确保智能体行为/策略的一致性。
`speak` 内容应该暴露给其它智能体或玩家。
`use_ability` 键应该能在主流程中访问到，从而确定游戏下一步的操作（例如是否使用能力）。

AgentScope 通过以下参数来自动对解析后的字典进行后处理。

- `keys_to_memory`: 应存储在智能体记忆中的键
- `keys_to_content`: 应存储在返回消息的 content 字段中的键，会暴露给其它智能体
- `keys_to_metadata`: 应存储在返回消息的元数据（metadata）字段中的键

.. note:: 如果提供了一个字符串，解析器将从解析后的字典中提取给定键的值。如果提供了一个字符串列表，将创建一个包含给定键的子字典。

下面是使用 `MarkdownJsonDictParser` 自动后处理解析后字典的示例。


.. GENERATED FROM PYTHON SOURCE LINES 315-340

.. code-block:: Python


    parser = MarkdownJsonDictParser(
        content_hint='{"thought": "你的想法", "speak": "你对用户说的话", "use_ability": "是否使用能力"}',
        keys_to_memory=["thought", "speak"],
        keys_to_content="speak",
        keys_to_metadata="use_ability",
    )

    dummy_response = ModelResponse(
        text="""```json
    {
        "thought": "我应该...",
        "speak": "我不会使用我的能力",
        "use_ability": false
    }```
    """,
    )

    parsed_response = parser.parse(dummy_response)

    print("解析后的响应: ", parsed_response.parsed)
    print("存储到记忆", parser.to_memory(parsed_response.parsed))
    print("存储到消息 content 字段: ", parser.to_content(parsed_response.parsed))
    print("存储到消息 metadata 字段: ", parser.to_metadata(parsed_response.parsed))





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    解析后的响应:  {'thought': '我应该...', 'speak': '我不会使用我的能力', 'use_ability': False}
    存储到记忆 {'thought': '我应该...', 'speak': '我不会使用我的能力'}
    存储到消息 content 字段:  我不会使用我的能力
    存储到消息 metadata 字段:  False




.. GENERATED FROM PYTHON SOURCE LINES 341-349

这里我们展示如何创建一个智能体，它在 `reply` 方法中通过以下步骤实现自动化的后处理。

1. 在提示中放入格式说明，以指导 LLM 生成所需的输出
2. 解析 LLM 的返回值
3. 使用 `to_memory`、`to_content` 和 `to_metadata` 方法后处理解析后的字典

.. tip:: 通过更改不同的解析器，智能体可以适应不同的场景，并以各种格式生成结构化输出。


.. GENERATED FROM PYTHON SOURCE LINES 349-402

.. code-block:: Python


    from agentscope.models import DashScopeChatWrapper
    from agentscope.agents import AgentBase


    class Agent(AgentBase):
        def __init__(self):
            self.name = "Alice"
            super().__init__(name=self.name)

            self.sys_prompt = f"你是一个名为{self.name}的有用助手。"

            self.model = DashScopeChatWrapper(
                config_name="_",
                model_name="qwen-max",
            )

            self.parser = MarkdownJsonDictParser(
                content_hint='{"thought": "你的想法", "speak": "你对用户说的话", "use_ability": "是否使用能力"}',
                keys_to_memory=["thought", "speak"],
                keys_to_content="speak",
                keys_to_metadata="use_ability",
            )

            self.memory.add(Msg("system", self.sys_prompt, "system"))

        def reply(self, msg):
            self.memory.add(msg)

            prompt = self.model.format(
                self.memory.get_memory(),
                # 指示模型按要求的格式作答
                Msg("system", self.parser.format_instruction, "system"),
            )

            response = self.model(prompt)

            parsed_response = self.parser.parse(response)

            self.memory.add(
                Msg(
                    name=self.name,
                    content=self.parser.to_memory(parsed_response.parsed),
                    role="assistant",
                ),
            )

            return Msg(
                name=self.name,
                content=self.parser.to_content(parsed_response.parsed),
                role="assistant",
                metadata=self.parser.to_metadata(parsed_response.parsed),
            )








.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 11.792 seconds)


.. _sphx_glr_download_build_tutorial_structured_output.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: structured_output.ipynb <structured_output.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: structured_output.py <structured_output.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: structured_output.zip <structured_output.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_