> 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/ti-gong-fang/ai-provider.md).

# AI 提供商

使用 Neuron，你只需一行代码即可在各个 LLM 提供商之间切换，而不会对你的智能体实现造成任何影响。

### Anthropic

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
            parameters: [], // 添加自定义参数（temperature、logprobs 等）
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

#### Anthropic 提示缓存

Anthropic 提供商提供了一个专用方法 `systemPromptBlocks()` 以利用系统提示缓存。无需使用 `instructions()` Agent 类中的方法，你可以将提示定义和缓存类型定义直接传递给提供商实例。

```php
class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_KEY',
            model: 'ANTHROPIC_MODEL'
        )->systemPromptBlocks([
            ['type' => 'text', 'text' => '静态说明...', 'cache_control' => ['type' => 'ephemeral']],
            ['type' => 'text', 'text' => '动态上下文...']
        ]);
    }
}
```

### Google Vertex AI 上的 Anthropic

要使用此提供商，你需要安装 google auth 的 Composer 包：

```shellscript
composer require google/auth
```

下面是使用语法 `AnthropicVertex` 在你的智能体中。

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\AnthropicVertex;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new AnthropicVertex(
            pathJsonCredentials: 'GOOGLE_FILE_CREDENTIALS_PATH',
            location: 'GOOGLE_LOCATION',
            projectId: 'GOOGLE_PROJECT_ID',
            model: 'ANTHROPIC_MODEL',
            parameters: [], // 添加自定义参数（temperature、logprobs 等）
        );
    }
}
```

### OpenAIResponses

此组件使用最新的 OpenAI responses API：

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\OpenAI\Responses\OpenAIResponses;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new OpenAIResponses(
            key: 'OPENAI_API_KEY',
            model: 'OPENAI_MODEL',
            parameters: [], // 添加自定义参数（temperature、logprobs 等）
            strict_response: false, // 严格结构化输出
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

### OpenAI

此组件使用旧版 OpenAI completions API：

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\OpenAI\OpenAI;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new OpenAI(
            key: 'OPENAI_API_KEY',
            model: 'OPENAI_MODEL',
            parameters: [], // 添加自定义参数（temperature、logprobs 等）
            strict_response: false, // 严格结构化输出
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

### AzureOpenAI

此提供商允许你连接 Azure 云平台提供的 OpenAI 模型。

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\AzureOpenAI;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new AzureOpenAI(
            key: 'AZURE_API_KEY',
            endpoint: 'AZURE_ENDPOINT',
            model: 'OPENAI_MODEL',
            version: 'AZURE_API_VERSION'
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

### OpenAILike

此类简化了与提供相同数据格式的官方 OpenAI API 的提供商之间的连接。

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\OpenAILike;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new OpenAILike(
            baseUri: 'https://api.together.xyz/v1',
            key: 'API_KEY',
            model: 'MODEL',
            parameters: [], // 添加自定义参数（temperature、logprobs 等）
            strict_response: false, // 严格结构化输出
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

### Ollama

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Ollama\Ollama;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Ollama(
            url: 'OLLAMA_URL',
            model: 'OLLAMA_MODEL',
            parameters: [], // 添加自定义参数（temperature、logprobs 等）
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

### Gemini

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Gemini\Gemini;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Gemini(
            key: 'GEMINI_API_KEY',
            model: 'GEMINI_MODEL',
            parameters: [], // 添加自定义参数（temperature、logprobs 等）
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

### Vertex AI 上的 Gemini

要使用此提供商，你需要安装 google auth 的 Composer 包：

```bash
composer require google/auth
```

下面是使用语法 `GeminiVertex` 在你的智能体中。

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Gemini\GeminiVertex;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new GeminiVertex(
            pathJsonCredentials: 'GOOGLE_FILE_CREDENTIALS_PATH',
            location: 'GOOGLE_LOCATION',
            projectId: 'GOOGLE_PROJECT_ID',
            model: 'GEMINI_MODEL',
            parameters: [], // 添加自定义参数（temperature、logprobs 等）
        );
    }
}
```

### Mistral

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Mistral\Mistral;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Mistral(
            key: 'MISTRAL_API_KEY',
            model: 'MISTRAL_MODEL',
            parameters: [], // 添加自定义参数（temperature、logprobs 等）
            strict_response: false, // 严格结构化输出
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

### ZAI

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\ZAI\ZAI;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new ZAI(
            key: 'ZAI_API_KEY',
            model: 'glm-5',
            parameters: [], // 添加自定义参数（temperature、logprobs 等）
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

### HuggingFace

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\HuggingFace\HuggingFace;
use NeuronAI\Providers\HuggingFace\InferenceProvider;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new HuggingFace(
            key: 'HF_ACCESS_TOKEN',
            model: 'mistralai/Mistral-7B-Instruct-v0.3',
            // https://huggingface.co/docs/inference-providers/en/index
            inferenceProvider: InferenceProvider::HF_INFERENCE,
            parameters: [
                'max_tokens' => 500,
                'temperature' => 0.5
            ]
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

### Deepseek

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Deepseek\Deepseek;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Deepseek(
            key: 'DEEPSEEK_API_KEY',
            model: 'DEEPSEEK_MODEL',
            parameters: [], // 添加自定义参数（temperature、logprobs 等）
            strict_response: false, // 严格结构化输出
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

### Grok（X-AI）

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\XAI\Grok;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Grok(
            key: 'GROK_API_KEY',
            model: 'grok-4',
            parameters: [], // 添加自定义参数（temperature、logprobs 等）
            strict_response: false, // 严格结构化输出
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

### AWS Bedrock Runtime

要使用 `BedrockRuntime` 提供商，你需要安装 [`aws/aws-sdk-php`](https://github.com/aws/aws-sdk-php) 包。

```bash
composer require aws/aws-sdk-php
```

下面可以找到在你的智能体中使用它的语法。

```php
namespace App\Neuron;

use Aws\BedrockRuntime\BedrockRuntimeClient;
use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\AWS\BedrockRuntime;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        $client = new BedrockRuntimeClient([
            'version' => 'latest',
            'region' => 'us-east-1',
            'credentials' => [
                'key' => 'AWS_BEDROCK_KEY',
                'secret' => 'AWS_BEDROCK_SECRET',
            ],
        ]);
        
        return new BedrockRuntime(
            client: $client,
            model: 'AWS_BEDROCK_MODEL',
            inferenceConfig: []
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

### Cohere

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Cohere\Cohere;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Cohere(
            key: 'COHERE_API_KEY',
            model: 'command-a-reasoning-08-2025',
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

### Alibaba DashScope

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Alibaba\DashScopeOpenAI;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new DashScopeOpenAI(
            key: 'DS_API_KEY',
            model: 'wan2.6-t2i',
        );
    }
}

$message = MyAgent::make()
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

echo $message->getContent();
// 嗨，今天我能帮你什么？
```

## 路由

官方 [Neuron Router](https://github.com/neuron-core/router) 在 Agent 会话和提供商 API 之间增加一层可靠性与管理层，为你和你的应用程序带来多项关键优势。

#### 用于高可用性的提供商故障切换 <a href="#provider-failover-for-high-availability" id="provider-failover-for-high-availability"></a>

提供商 API 偶尔会出现宕机或速率限制。使用 RouterProvider 时，你的请求会在多个底层提供商之间自动故障切换。若某个提供商不可用或受到速率限制，路由器会无缝切换到另一个，从而保持你的会话不中断。

#### 路由逻辑控制

你可以使用如下路由逻辑 `轮询` 作为负载均衡器， `内容规则` 根据消息中的内容块（图片、文件、音频、视频）来路由请求，或者 `难度规则` 以确定哪个模型最适合处理传入的提示。&#x20;

首先安装该包：

```shellscript
composer require neuron-core/router
```

现在使用 `RouterProvider` 类，就像在你的智能体类中使用其他提供商一样：

```php
use NeuronAI\Router\RouterProvider;
use NeuronAI\Router\Rules\MethodRule;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\Providers\OpenAI\OpenAI;

class MyAgent extens Agent
{
    protected function provider(): AIProviderInterface
    {
        return RouterProvider::make()
            ->addProvider('anthropic', new Anthropic(
                key: 'ANTHROPIC_API_KEY',
                model: 'claude-sonnet-4-20250514',
            ))
            ->addProvider('openai', new OpenAI(
                key: 'OPENAI_API_KEY',
                model: 'gpt-4o',
            ))
            ->setRule(
                new RoundRobinRule(['anthropic', 'openai'])
            );
    }

    protected function instructions(): string
    {...}

    protected function tools(): array
    {...}
}
```

在上面的示例中，我们使用 `RoundRobinRule` 使路由器在已连接的 AI 提供商之间充当负载均衡器。该包自带多种内置规则，包括一个 LLM 分类器，可根据提示难度分数将调用路由到合适的模型： <https://github.com/neuron-core/router#difficultyrule>

## 自定义 HTTP 客户端

提供商使用 HTTP 客户端与远程服务通信。你可以通过显式传入一个带有自定义构造参数的实例来定制 HTTP 客户端配置，例如超时、自定义请求头等。

```php
use NeuronAI\Providers\HttpClientOptions;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Ollama(
            url: 'OLLAMA_URL',
            model: 'OLLAMA_MODEL',
            httpClient: new GuzzleHttpClient(
                customHeaders: [...],
                timeout: 30,
            )
        );
    }
}
```

## 实现自定义提供商

如果你想创建一个新的提供商，你需要实现 `AIProviderInterface` 接口：

```php
namespace NeuronAI\Providers;

use NeuronAI\Chat\Messages\Message;
use NeuronAI\Tools\ToolInterface;
use NeuronAI\Providers\MessageMapperInterface;

interface AIProviderInterface
{
    /**
     * 向 LLM 发送预定义指令。
     */
    public function systemPrompt(?string $prompt): AIProviderInterface;

    /**
     * 设置要暴露给 LLM 的工具。
     *
     * @param array<ToolInterface> $tools
     */
    public function setTools(array $tools): AIProviderInterface;
    
    /**
     * 负责将 NeuronAI 消息映射为 AI 提供商格式的组件。
     */
    public function messageMapper(): MessageMapperInterface;

    /**
     * 向 AI 智能体发送提示。
     */
    public function chat(array $messages): Message;
    
    /**
     * 生成 LLM 响应。
     */
    public function stream(array|string $messages, callable $executeToolsCallback): \Generator;
    
    /**
     * 经模式验证的响应。
     */
    public function structured(string $class, Message|array $messages, int $maxRetry = 1): mixed;
}
```

该 `chat` 方法应包含对底层 LLM 的调用。如果提供商不支持工具和函数调用，你可以用占位实现。

这是一个新的 AI 提供商实现的基本模板。

```php
namespace App\Neuron\Providers;

use GuzzleHttp\Client;
use GuzzleHttp\RequestOptions;
use NeuronAI\Chat\Messages\AssistantMessage;
use NeuronAI\Chat\Messages\Message;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\HandleWithTools;
use NeuronAI\Providers\MessageMapperInterface;

class MyAIProvider implements AIProviderInterface
{
    use HandleWithTools;
    
    /**
     * HTTP 客户端。
     *
     * @var Client
     */
    protected Client $client;

    /**
     * 系统指令。
     *
     * @var string
     */
    protected string $system;

    /**
     * 负责将 NeuronAI 消息映射为 AI 提供商格式的组件。
     *
     * @var MessageMapperInterface
     */
    protected MessageMapperInterface $messageMapper;
    
    public function __construct(
        protected string $key,
        protected string $model
    ) {
        $this->client = new Client([
            'base_uri' => 'https://api.provider.com/v1',
            'headers' => [
                'Content-Type' => 'application/json',
                'Authorization' => "Bearer {$this->key}",
            ]
        ]);
    }

    /**
     * @inerhitDoc
     */
    public function systemPrompt(string $prompt): AIProviderInterface
    {
        $this->system = $prompt;
        return $this;
    }

    public function messageMapper(): MessageMapperInterface
    {
        return $this->messageMapper ?? $this->messageMapper = new MessageMapper();
    }

    /**
     * @inerhitDoc
     */
    public function chat(array $messages): Message
    {
        $result = $this->client->post('chat', [
            RequestOptions::JSON => [
                'model' => $this->model,
                'messages' => \array_map(function (Message $message) {
                    return $message->jsonSerialize();
                }, $messages)
            ]
        ])->getBody()->getContents();
        
        $result = \json_decode($result, true);

        return new AssistantMessage($result['content']);
    }
}
```

在创建自己的实现后，你可以在智能体中使用它：

```php
namespace App\Neuron;

use App\Neuron\Providers\MyAIProvider;
use NeuronAI\Agent;
use NeuronAI\Providers\AIProviderInterface;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new MyAIProvider (
            key: 'PROVIDER_API_KEY',
            model: 'PROVIDER_MODEL',
        );
    }
}
```

{% hint style="warning" %}
我们强烈建议你通过 PR 将新的提供商实现提交到官方仓库，或者通过其他 [Inspector.dev](https://inspector.dev/developer-support/) 支持渠道。新的实现可以在社区的推动下获得显著进步。
{% endhint %}