> 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/async.md).

# HTTP 与异步

在异步上下文中运行工作流。

Neuron 支持异步执行和代理的并行处理，使你能够高效地同时处理多个操作。Neuron 的异步执行方式具有以下几个优势：

**与框架无关**：你只需一个简单的适配器，就可以让代理和 RAG 以异步友好的方式适配最常见的异步环境，无需对你的实现做任何修改。

**提供方兼容性**：我们的解决方案与您使用的提供方无关。你可以让使用不同提供方和模型的工作流或多代理系统在异步循环中顺畅运行。

**可扩展性**：处理大量数据的应用（商品分类、内容审核、数据标注）会显著受益于并发处理能力。

### 并发 vs 异步

并发是管理任务的高层概念，可能涉及多线程/多核（并行），而异步则使用事件循环/回调，让任务按非顺序方式运行，非常适合 I/O 密集型工作，无需等待。

并发是关于同时管理许多事情，而异步则是单个线程如何高效地管理多个 I/O 操作。

AI 代理通常被视为 I/O 密集型软件，因为对模型执行推理的 HTTP 请求通常需要几秒钟才能完成。在标准 PHP 环境中，这段时间里你的应用程序只会等待。在本文档的这一部分，我们为你提供了几个高效运行多个代理的解决方案。

## 并发

你不需要 Neuron 的任何特定功能就能并行运行多个代理。你只需要你的 PHP 应用程序能够跨越多个进程，以同时处理多个代理的执行。你可以使用像 [spatie/fork](https://github.com/spatie/fork)这样的 PHP 库，或者像 [Laravel 并发](https://laravel.com/docs/master/concurrency)，或 [Symfony 进程](https://symfony.com/doc/current/components/process.html).

而异步则是另一回事。

## 异步

Neuron 的早期版本与 Guzzle 客户端紧密耦合，用于向提供方的 API 发起模型推理的 HTTP 请求。Guzzle 是一个很棒的工具，但它与真正的异步事件循环不兼容，例如以下框架提供的事件循环： [Amp](https://github.com/amphp/amp) 和 [ReactPHP](https://github.com/reactphp/reactphp).

要在这样的异步环境中运行代理，需要集成其特定实现。这就是 Neuron 附带一个简单的 `HttpClientInterface` ，它可以被实现，以允许 AI 提供方在异步循环中顺畅地运行 HTTP 请求。

默认情况下，框架使用 Guzzle 实现，但你可以根据需要注入自定义 HTTP 客户端。我们已经为最常见的异步框架提供了实现。

### AmpHttpClient

如果你想使用 Amp 来运行多个异步代理请求，你需要安装 `amphp/http-client` .

```bash
composer require amphp/http-client
```

现在你可以将内置的 `AmpHttpClient` 适配器注入到提供方中：

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\HttpClient\AmpHttpClient;
use NeuronAI\Providers\Anthropic\Anthropic;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        // 对任何提供方都一样（Anthropic、OpenAI、Ollama、Gemini 等）
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
            httpClient: new AmpHttpClient(),
        );
    }
}
```

现在你可以使用 Amp 的 async/await 模式来运行多个代理请求，从而异步运行多个代理：

```php
use Amp\Future;

use function Amp\async;

$handler1 = MyAgent::make()->setThreadId('chat_id_x')->chat(new UserMessage('Hi!'));
$handler2 = MyAgent::make()->setThreadId('chat_id_xx')->chat(new UserMessage('Hi!'));
$handler3 = MyAgent::make()->setThreadId('chat_id_xxx')->chat(new UserMessage('Hi!'));

// 并行运行三个请求
[$response1, $response2, $response3] = Future\await([
    async(fn() => $handler1->getMessage()), 
    async(fn() => $handler2->getMessage()),
    async(fn() => $handler3->getMessage()),
]);

// 打印内容
echo $response1->getContent();
echo $response2->getContent();
echo $response3->getContent();
```

### 异步 RAG

HTTP 客户端抽象也被所有其他框架组件接受，例如嵌入提供方和向量存储。你可以向所有这些组件提供一个异步客户端，并且也能异步运行数据加载流水线。

```php
class MyChatBot extends RAG
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
            httpClient: new AmpHttpClient(),
        );
    }
    
    protected function embeddings(): EmbeddingsProviderInterface
    {
        return new VoyageEmbeddingsProvider(
            key: 'OPENAI_API_KEY',
            model: 'OPENAI_MODEL'
            httpClient: new AmpHttpClient(),
        );
    }
    
    protected function vectorStore(): VectorStoreInterface
    {
        return new PineconeVectorStore(
            key: 'PINECONE_API_KEY',
            indexUrl: 'PINECONE_INDEX_URL',
            httpClient: new AmpHttpClient(),
        );
    }
}
```

### 护栏

异步执行代理的能力，使得可以在主请求进行的同时运行输入护栏。通常你可以创建一个专门的代理来针对用户输入执行安全检查，并使用结构化响应来获取结果。

你可以并行运行这两个请求，并在向用户返回响应之前检查护栏结果。并行运行这两个请求使你能够在不影响用户体验的情况下执行安全控制。

```php
use Amp\Future;
use function Amp\async;

$input = new UserMessage('Hi!');

// 并行运行三个请求
[$response, $guardrail] = Future\await([
    async(fn() => MyAgent::make()
        ->setThreadId('chat_id')
        ->chat($input)
        ->getMessage()),
        
    async(fn() => GuardrailAgent::make()
        ->setThreadId('guardrails')
        ->structured($input, Guardrail::class)),
]);

if (! $guardrail->valid) {
    throw \Exception('内容政策违规。');
}

// 打印内容
echo $response->getContent();
```

## 可停止的 HttpClient

在流式输出进行到一半时停止答案，用于“停止生成”按钮。提供方会将截至目前流式传输的文本作为部分内容保留，并将其存储在聊天历史中。

将客户端包装在 `可停止的 HttpClient` 中，并提供一个谓词，供提供方在读取每个事件之前询问；“停止”端点只会抛出一个标志，由谓词读取，而这两个进程共享的任何存储都可以：

```php
use NeuronAI\HttpClient\Curl\CurlHttpClient;
use NeuronAI\HttpClient\StoppableHttpClient;

protected function provider(): AIProviderInterface
{
    return new Anthropic(
        key: $this->apiKey,
        model: 'claude-sonnet-4-6',
        // 缓存或任何共享存储都可以（Laravel 或 Symfony Cache、Redis、数据库行）
        httpClient: new StoppableHttpClient(
            new CurlHttpClient(), 
            fn (): bool => Cache::pull("stop:{$this->getThreadId()}", false)
        ),
    );
}
```
