> 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/zhi-neng-ti/messages.md).

# 消息

## 统一消息层

Neuron 架构的主要优势之一，是用于与多个 AI 提供商交互的统一消息层。开发者不必再费力应对 OpenAI、Anthropic、Gemini、Ollama 以及无数其他提供商各不相同的响应格式，而是使用一个简洁统一的抽象层，它会在幕后处理所有复杂性。你的代码将不再依赖于你所使用的特定 LLM 引擎。

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

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

## 什么是消息

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

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

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

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

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

$response = MyAgent::make()
    ->chat(new UserMessage("嗨，你是谁？"))
    ->getMessage();

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

## 内容块

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

消息可以包含任意数量的块，甚至可以包含每种类型的多个块。Neuron 会自动将块类型映射为适合各个提供商的格式。

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

```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,
        ...
        // 其他内容块 
    };
}
```

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

```php
$response = MyAgent::make()
    ->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\Enum\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\Enum\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)
]);
```

根据你的提供商规范，你也可以对 Image、Video 等使用相同方式。

### 音频

```php
use NeuronAI\Chat\Enum\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\Enum\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::MP$
    )
);

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