> ## Documentation Index
> Fetch the complete documentation index at: https://speshu.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Поиск в интернете

> Как добавить веб-поиск к любой AI модели

SpeShu.AI поддерживает веб-поиск для любой модели — от GPT-5 до Claude и Gemini. Модель получает актуальные данные из интернета и включает ссылки на источники в ответ.

## Быстрый старт

### Chat Completions API

Добавьте плагин `web` в запрос:

```typescript theme={null}
import OpenAI from 'openai';

const openai = new OpenAI({
  baseURL: 'https://speshu.ai/api/v1',
  apiKey: '<SPESHU_AI_API_KEY>'
});

const completion = await openai.chat.completions.create({
  model: 'openai/gpt-5.5',
  messages: [
    { role: 'user', content: 'Последние новости о квантовых компьютерах' }
  ],
  plugins: [{ id: 'web' }]
});

console.log(completion.choices[0].message.content);
console.log(completion.choices[0].message.annotations); // ссылки на источники
```

### Responses API

Используйте `tools` с типом `web_search_preview`:

```typescript theme={null}
const response = await fetch('https://speshu.ai/api/v1/responses', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <SPESHU_AI_API_KEY>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.5',
    input: 'Последние новости о квантовых компьютерах',
    tools: [{ type: 'web_search_preview' }]
  })
});
```

## Способы активации

| Способ                                  | API              | Совместимость | Описание                                 |
| --------------------------------------- | ---------------- | ------------- | ---------------------------------------- |
| `plugins: [{id: "web"}]`                | Chat Completions | Все модели    | Рекомендуемый. Явное подключение плагина |
| `tools: [{type: "web_search_preview"}]` | Responses API    | Все модели    | OpenAI-совместимый формат                |
| `web_search_options`                    | Chat Completions | Ограниченный  | Нативный параметр OpenAI                 |

## Как работает

1. **Запрос с плагином `web`** — вы отправляете запрос с включённым веб-поиском
2. **Определение типа модели** — система проверяет, поддерживает ли модель нативный поиск
3. **Выполнение поиска**:
   * Для моделей с нативным поиском (OpenAI, Anthropic, xAI, Perplexity) — активируется встроенный web search провайдера
   * Для остальных моделей (Gemini, DeepSeek и др.) — поиск выполняется через Exa и результаты добавляются в контекст модели
4. **Ответ с цитатами** — модель формирует ответ на основе найденных данных. Ссылки на источники возвращаются в `annotations`

## Формат ответа

Результаты поиска возвращаются в поле `annotations`:

```json theme={null}
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Квантовый компьютер IBM достиг рекордных показателей...",
      "annotations": [
        {
          "type": "url_citation",
          "url_citation": {
            "url": "https://example.com/quantum",
            "title": "IBM Quantum Breakthrough",
            "start_index": 0,
            "end_index": 55
          }
        }
      ]
    }
  }]
}
```

### Поля аннотации

| Поле                       | Тип    | Описание                      |
| -------------------------- | ------ | ----------------------------- |
| `type`                     | string | Всегда `"url_citation"`       |
| `url_citation.url`         | string | URL источника                 |
| `url_citation.title`       | string | Заголовок страницы            |
| `url_citation.start_index` | number | Начало цитаты в тексте ответа |
| `url_citation.end_index`   | number | Конец цитаты в тексте ответа  |

## Настройки плагина

| Параметр        | Тип     | По умолчанию | Описание                                                    |
| --------------- | ------- | ------------ | ----------------------------------------------------------- |
| `max_results`   | number  | 5            | Максимальное количество результатов поиска                  |
| `search_prompt` | string  | —            | Собственный промпт для поиска (иначе модель формирует сама) |
| `engine`        | string  | auto         | Поисковый движок: `native`, `exa` или auto                  |
| `enabled`       | boolean | true         | Включить/выключить плагин                                   |

### Поисковые движки

| Движок              | Описание                                                         | Когда используется                       |
| ------------------- | ---------------------------------------------------------------- | ---------------------------------------- |
| `native`            | Встроенный поиск провайдера (OpenAI, Anthropic, xAI, Perplexity) | Когда модель поддерживает нативный поиск |
| `exa`               | Поиск через Exa — ключевые слова + эмбеддинги                    | Универсальный, работает с любой моделью  |
| auto (по умолчанию) | `native` если доступен, иначе `exa`                              | Рекомендуется                            |

## Совместимость

Нативный веб-поиск поддерживается **38 моделями** от 4 провайдеров. Для остальных моделей используется поиск через Exa.

| Провайдер  | Нативный поиск | Примеры                                              |
| ---------- | -------------- | ---------------------------------------------------- |
| OpenAI     | ✅              | gpt-5.5-pro, o3, o4-mini, gpt-4o-search-preview      |
| Anthropic  | ✅              | claude-opus-4.6, claude-sonnet-4.5, claude-haiku-4.5 |
| xAI        | ✅              | grok-4, grok-3, grok-3-mini                          |
| Perplexity | ✅              | sonar, sonar-pro, sonar-deep-research                |
| Google     | через Exa      | gemini-2.5-pro, gemini-2.5-flash                     |
| DeepSeek   | через Exa      | deepseek-r1, deepseek-chat                           |

## Советы и лучшие практики

**Не комбинируйте с json\_object**
Формат ответа `json_object` или `json_schema` может мешать модели включать цитаты и ссылки на источники.

**Используйте search\_prompt для точности**
Параметр `search_prompt` позволяет задать конкретный поисковый запрос вместо того, чтобы модель формировала его сама.

**Проверяйте annotations**
Наличие `url_citation` в `annotations` подтверждает, что веб-поиск был выполнен и модель использовала найденные данные.