> 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-shang/ai-provider.md).

# AI 提供商

与 LLM 提供商交互，或扩展框架以实现新的提供商。

使用 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()
    ->setThreadId('chat_id')
    ->chat(new UserMessage("Hi!"))
    ->getMessage();

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

#### Anthropic 提示缓存

要利用 Anthropic 提示缓存，您应将智能体指令提供为一个数组，数组元素为 `SystemContent`:

```php
use NeuronAI\Chat\Messages\ContentBlocks\SystemContent;

class MyAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new Anthropic(
            key: 'ANTHROPIC_API_KEY',
            model: 'ANTHROPIC_MODEL',
        );
    }

    protected function instructions(): string|array
    {
        return [
            new SystemContent('fixed part')->cache(),
            new SystemContent('dynamic part'),
        ];
    }
}
```

### Google Vertex AI 上的 Anthropic

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

```bash
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-core/router](https://github.com/neuron-core/router) 软件包，您可以将推理调用路由到不同的提供商或模型，而对智能体本身完全透明。路由器还提供回退策略：当主提供商因服务宕机或超出使用限制而失败时，可切换到第二个提供商。

首先安装该软件包：

```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;
    
    /**
     * 经过 Schema 验证的响应。
     */
    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 %}