要创建ChatMessage 实例，请使用from_user, from_system, from_assistant 和from_tool 类方法。

然后可以使用ChatMessage 的内容来检查text, texts, image, images, tool_call, tool_calls, tool_call_result 和tool_call_results 属性。

如果您正在寻找此数据类方法和参数的详细信息，请转到我们的 API 文档。

内容类型

ChatMessage 当前支持TextContent, ImageContent, ToolCall 和ToolCallResult 内容类型。

@dataclass
class TextContent:
    """
    The textual content of a chat message.

    :param text: The text content of the message.
    """

    text: str

@dataclass
class ToolCall:
    """
    Represents a Tool call prepared by the model, usually contained in an assistant message.

    :param tool_name: The name of the Tool to call.
    :param arguments: The arguments to call the Tool with.
    :param id: The ID of the Tool call.
    """

    tool_name: str
    arguments: Dict[str, Any]
    id: Optional[str] = None  # noqa: A003

@dataclass
class ToolCallResult:
    """
    Represents the result of a Tool invocation.

    :param result: The result of the Tool invocation.
    :param origin: The Tool call that produced this result.
    :param error: Whether the Tool invocation resulted in an error.
    """

    result: str
    origin: ToolCall
    error: bool

@dataclass
class ImageContent:
    """
    The image content of a chat message.

    :param base64_image: A base64 string representing the image.
    :param mime_type: The MIME type of the image (e.g. "image/png", "image/jpeg").
        Providing this value is recommended, as most LLM providers require it.
        If not provided, the MIME type is guessed from the base64 string, which can be slow and not always reliable.
    :param detail: Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
    :param meta: Optional metadata for the image.
    :param validation: If True (default), a validation process is performed:
        - Check whether the base64 string is valid;
        - Guess the MIME type if not provided;
        - Check if the MIME type is a valid image MIME type.
        Set to False to skip validation and speed up initialization.
    """

    base64_image: str
    mime_type: Optional[str] = None
    detail: Optional[Literal["auto", "high", "low"]] = None
    meta: Dict[str, Any] = field(default_factory=dict)
    validation: bool = True

该ImageContent 数据类还提供了两个便捷的类方法from_file_path 和from_url。有关更多详细信息，请参阅我们的 API 文档。

使用 ChatMessage

以下示例演示了如何创建ChatMessage 并检查其属性。

from_user 与 TextContent

from haystack.dataclasses import ChatMessage

user_message = ChatMessage.from_user("What is the capital of Australia?")

print(user_message)
>>> ChatMessage(
>>>    _role=<ChatRole.USER: 'user'>,
>>>    _content=[TextContent(text='What is the capital of Australia?')],
>>>    _name=None,
>>>    _meta={}
>>>)

print(user_message.text)
>>> What is the capital of Australia?

print(user_message.texts)
>>> ['What is the capital of Australia?']

from_user 与 TextContent 和 ImageContent

from haystack.dataclasses import ChatMessage, ImageContent

capybara_image_url = (
    "https://upload.wikimedia.org/wikipedia/commons/thumb/e/e1/"
    "Cattle_tyrant_%28Machetornis_rixosa%29_on_Capybara.jpg/"
    "960px-Cattle_tyrant_%28Machetornis_rixosa%29_on_Capybara.jpg?download"
)

image_content = ImageContent.from_url(capybara_image_url, detail="low")

user_message = ChatMessage.from_user(
	content_parts=[
		"What does the image show?",
		image_content
		])

print(user_message)
>>> ChatMessage(
>>>     _role=<ChatRole.USER: 'user'>,
>>>     _content=[
>>>         TextContent(text='What does the image show?'),
>>>         ImageContent(
>>>             base64_image='/9j/4...',
>>>             mime_type='image/jpeg',
>>>             detail='low',
>>>             meta={
>>>                 'content_type': 'image/jpeg',
>>>                 'url': '...'
>>>             }
>>>         )
>>>     ],
>>>     _name=None,
>>>     _meta={}
>>> )

print(user_message.text)
>>> What does the image show?

print(user_message.texts)
>>> ['What does the image show?']

print(user_message.image)
>>> ImageContent(
>>>     base64_image='/9j/4...',
>>>     mime_type='image/jpeg',
>>>     detail='low',
>>>     meta={
>>>         'content_type': 'image/jpeg',
>>>         'url': '...'
>>>     }
>>> )

from_assistant 与 TextContent

from haystack.dataclasses import ChatMessage

assistant_message = ChatMessage.from_assistant("How can I assist you today?")

print(assistant_message)
>>> ChatMessage(
>>>    _role=<ChatRole.ASSISTANT: 'assistant'>,
>>>    _content=[TextContent(text='How can I assist you today?')],
>>>    _name=None,
>>>    _meta={}
>>>)

print(assistant_message.text)
>>> How can I assist you today?

print(assistant_message.texts)
>>> ['How can I assist you today?']

from_assistant 与 ToolCall

from haystack.dataclasses import ChatMessage, ToolCall

tool_call = ToolCall(tool_name="weather_tool", arguments={"location": "Rome"})

assistant_message_w_tool_call = ChatMessage.from_assistant(tool_calls=[tool_call])

print(assistant_message_w_tool_call)
>>> ChatMessage(
>>>    _role=<ChatRole.ASSISTANT: 'assistant'>,
>>>    _content=[ToolCall(tool_name='weather_tool', arguments={'location': 'Rome'}, id=None)],
>>>    _name=None,
>>>    _meta={}
>>>)

print(assistant_message_w_tool_call.text)
>>> None

print(assistant_message_w_tool_call.texts)
>>> []

print(assistant_message_w_tool_call.tool_call)
>>> ToolCall(tool_name='weather_tool', arguments={'location': 'Rome'}, id=None)

print(assistant_message_w_tool_call.tool_calls)
>>> [ToolCall(tool_name='weather_tool', arguments={'location': 'Rome'}, id=None)]

print(assistant_message_w_tool_call.tool_call_result)
>>> None

print(assistant_message_w_tool_call.tool_call_results)
>>> []

from_tool

from haystack.dataclasses import ChatMessage

tool_message = ChatMessage.from_tool(tool_result="temperature: 25°C", origin=tool_call, error=False)

print(tool_message)
>>> ChatMessage(
>>>    _role=<ChatRole.TOOL: 'tool'>,
>>>    _content=[ToolCallResult(
>>>							   result='temperature: 25°C',
>>>                origin=ToolCall(tool_name='weather_tool', arguments={'location': 'Rome'}, id=None),
>>>                error=False
>>>                )],
>>>    _name=None,
>>>    _meta={}
>>>)

print(tool_message.text)
>>> None

print(tool_message.texts)
>>> []

print(tool_message.tool_call)
>>> None

print(tool_message.tool_calls)
>>> []

print(tool_message.tool_call_result)
>>> ToolCallResult(
>>>     result='temperature: 25°C',
>>>     origin=ToolCall(tool_name='weather_tool', arguments={'location': 'Rome'}, id=None),
>>>     error=False
>>> )

print(tool_message.tool_call_results)
>>> [
>>>     ToolCallResult(
>>>         result='temperature: 25°C',
>>>         origin=ToolCall(tool_name='weather_tool', arguments={'location': 'Rome'}, id=None),
>>>         error=False
>>>     )
>>> ]

从旧版 ChatMessage (2.9 版本之前) 迁移

在 Haystack 2.9 中，我们更新了ChatMessage 数据类，以获得更大的灵活性并支持多种内容类型：文本、工具调用和工具调用结果。

其中包含一些破坏性更改，因此我们建议您仔细阅读本指南以顺利迁移。

创建 ChatMessage

您不能再直接初始化ChatMessage，使用role, content 和meta.

而是使用以下类方法：from_assistant, from_user, from_system 和from_tool.
替换content 参数为text.

from haystack.dataclasses import ChatMessage

# LEGACY - DOES NOT WORK IN 2.9.0
message = ChatMessage(role=ChatRole.USER, content="Hello!")

# Use the class method instead
message = ChatMessage.from_user("Hello!")

访问 ChatMessage 属性

旧的content 属性现在是内部属性（_content).
使用以下属性检查ChatMessage 属性：
- role
- meta
- name
- text 和texts
- image 和images
- tool_call 和tool_calls
- tool_call_result 和tool_calls_results

from haystack.dataclasses import ChatMessage

message = ChatMessage.from_user("Hello!")

# LEGACY - DOES NOT WORK IN 2.9.0
print(message.content)

# Use the appropriate property instead
print(message.text)

from haystack.dataclasses import ChatMessage

message = ChatMessage.from_user("Hello!")

# LEGACY - DOES NOT WORK IN 2.9.0
print(message.content)

# Use the appropriate property instead
print(message.text)