> For the complete documentation index, see [llms.txt](https://docs.neuron-ai.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neuron-ai.dev/neuron-v3-zh/dai-li/messages.md).

# 消息

跨 AI 提供商和 LLM 的统一上下文单元。

## 统一消息层

Neuron 架构的一大优势是用于与多个 AI 提供方交互的统一消息层。开发者无需再费力应对 OpenAI、Anthropic、Gemini、Ollama 以及无数其他提供方各不相同的响应格式，而是可以使用一个单一而优雅的抽象层，在幕后处理所有复杂性。你的代码会变得与所使用的具体 LLM 引擎无关。

当你在应用中集成 Neuron Agents 时，你不会被锁定在任何特定提供方的生态系统或定价模式中。你可以在不同提供方之间无缝切换，以管理成本、环境，或者利用新模型发布带来的优势，立即享受这些改进，而无需进行大规模重构。

**消息层不仅限于简单的文本内容，还为多模态输入/输出提供统一接口** （文件、图像、视频、音频），适用于所有受支持的提供方，即使底层实现差异巨大也是如此。这一架构决策意味着你的 AI 智能体保持可移植且面向未来——当新的提供方出现或现有提供方更新其 API 时，你的应用代码无需更改，而 Neuron 的消息层会吸收所有适配复杂性。

## 什么是消息

消息是上下文的基本单元。它们代表模型的输入和输出，携带在与 LLM 交互时表示对话状态所需的内容和元数据。

消息是包含以下内容的对象：

* **角色** - 标识消息类型（例如 user、assistant）
* **内容块** - 表示消息的实际内容（如文本、图像、音频、文件等）
* **元数据** - 可选字段，例如额外的 LLM 响应信息。

下面是一个示例，展示如何向智能体发送用户消息并接收助手消息作为响应。

```php
use NeuronAI\\Chat\\Messages\\UserMssage;

$response = MyAgent::make()
    ->setThreadId('chat_id')
    ->chat(new UserMessage("Hi, who are you?"))
    ->getMessage();

echo $response->getContent();
```

## 内容块

你可以把消息的内容块看作发送给模型的数据载荷，或者看作模型为回答你的提示而生成的数据。消息可以包含一个扩展 `ContentBlock` 接口的对象列表。Neuron 为文本、图像、文件、音频和视频提供了专门的内容类型。

消息可以包含任意数量的块，甚至同类型的多个块。Neuron 会自动为每个提供方将块类型映射为相应格式。

你可以使用以下方式获取并处理消息中的块列表： `getContentBlocks()` 方法：

```php
$response = MyAgent::make()
    ->setThreadId('chat_id')
    ->chat(...)
    ->getMessage();

foreach ($response->getContentBlocks() as $block) {
    echo match($block::class) {
        ReasoningContent::class => "推理：".$block->content."\n\n",
        TextContent::class => $block->content,
        ...
        // 其他内容块 
    };
}
```

或者直接使用 `getContent()` 来获取所有文本内容的拼接结果：

```php
$response = MyAgent::make()
    ->setThreadId('chat_id')
    ->chat(new UserMessage("..."))
    ->getMessage();

// 将所有文本块拼接为一个字符串
echo $response->getContent();
```

{% hint style="info" %}

#### 验证模型能力

在使用特定内容块之前，你需要先验证模型是否具备解释你想发送的信息的能力（图像、音频、视频）。
{% endhint %}

### 文本

这个块表示消息中的文本部分。你可以在构造函数参数中使用一个简单字符串来初始化消息，或者显式添加一个 `TextContent` 块：

```php
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Chat\Messages\ContentBlocks\TextContent;

// 在构造函数中传入字符串会向消息中添加第一个 TextContentBlock
$message = new UserMessage("你好");

// 向消息中添加其他文本部分
$message->addContent(
    new TextContent("我叫 John。")
);

$message->addContent(
    new TextContent('请记得像专业礼宾员一样回答。')
);

// 将所有文本块拼接
echo $message->getContent();
// 你好，我叫 John。请记得像专业礼宾员一样回答。

// 或者获取文本内容块数组
$blocks = $message->getTextBlocks();
```

正如你所见，最终消息将由多个块组成。

### 推理

这个块会包含模型在最终文本响应之前生成的推理步骤。Neuron 会自动从模型响应中捕获它：

```php
// 与具备推理能力的模型聊天
$response = MyAgent::make()->chat(...)->getMessage();

foreach ($response->getContentBlocks() as $block) {
    echo match($block::class) {
        ReasoningContent::class => "推理：".$block->content."\n\n",
        TextContent::class => $block->content,
        ...
        // 其他内容块 
    };
}
```

### 图像

对于支持多模态的模型，你可以附加图像以及其他类型的内容，例如文件、音频和视频。

```php
use NeuronAI\\Chat\\MediaType;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Chat\Messages\ContentBlocks\ImageContent;

$message = new UserMessage("请描述这张图像");

$message->addContent(
    new ImageContent(
        source: 'https://placehold.co/600x400/EEE/31343C',
        sourceType: SourceType::URL,
        mediaType: MediaType::PNG
    )
);

$response = MyAgent::make()->chat($message)->getMessage();
echo $response->getContent();
```

### 文件

```php
use NeuronAI\\Chat\\MediaType;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\\Chat\\Messages\\ContentBlocks\\FileContent;

$message = new UserMessage("请总结这份文档");

$message->addContent(
    new FileContent(
        source: base64_encode(file_get_contents(__DIR__.'/invoice.pdf')),
        sourceType: SourceType::BASE64,
        mediaType: MediaType::PDF
    )
);

$response = MyAgent::make()->chat($message)->getMessage();
echo $response->getContent();
```

### 文件 ID

通常你可以将文件（图像或文档）以 URL 形式附加到消息中，或者以 base64 格式编码。许多提供方允许你先在其平台上上传一次文件，然后在消息中用一个简单的 ID 引用这些文件。这可以显著节省 token 消耗，并且可以提高模型响应速度。

在从提供方平台收到文件 ID 后，你可以使用以下方式向消息中添加文件块： `SourceType::ID`.

```php
// 引用之前已上传到提供方平台的文件 ID
$message = new UserMessage([
    new TextBlock('分析这个'),
    new FileBlock("file_id_xxxx", SourceType::ID)
]);
```

根据你的提供方规范，你也可以对图像、视频等执行相同操作。

### 音频

```php
use NeuronAI\\Chat\\MediaType;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\\Chat\\Messages\\ContentBlocks\\AudioContent;

$message = new UserMessage("请转写这段音频");

$message->addContent(
    new FileContent(
        source: base64_encode(file_get_contents(__DIR__.'/music.mp3')),
        sourceType: SourceType::BASE64,
        mediaType: MediaType::MP3
    )
);

$response = MyAgent::make()->chat($message)->getMessage();
echo $response ->getContent();
```

### 视频

```php
use NeuronAI\\Chat\\MediaType;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\\Chat\\Messages\\ContentBlocks\\VideoContent;

$message = new UserMessage("请总结这节课的内容。");

$message->addContent(
    new VideoContent(
        source: base64_encode(file_get_contents(__DIR__.'/lesson_1.mp4')),
        sourceType: SourceType::BASE64,
        mediaType: MediaType::MP4
    )
);

$response = MyAgent::make()->chat($message)->getMessage();
echo $response->getContent();
```
