Perplexity

Обзор

Perplexity — это OpenAI-совместимый API со встроенными возможностями web search и поддержкой reasoning. Meridian выполняет необходимые преобразования:

• OpenAI-совместимая база — за основу берётся chat-формат OpenAI.
• Параметры web search — режим поиска, фильтры по доменам, фильтры свежести и поиск по геолокации.
• Маппинг reasoning effort — reasoning.effort мапится в reasoning_effort Perplexity с особой обработкой значения "minimal".
• Возврат результатов поиска — цитаты, search results и видео включаются в ответ.
• Расширенный учёт usage — citation-токены, количество поисковых запросов и reasoning-токены учитываются отдельно.

Поддерживаемые операции

1. Chat Completions

Параметры запроса

Perplexity поддерживает большинство параметров OpenAI chat completion. Базовый справочник параметров — в разделе OpenAI Chat Completions.

Ограничения, специфичные для Perplexity

• Function calling не поддерживается: tools и tool_choice тихо отбрасываются.
• Игнорируемые параметры: stop, logit_bias, logprobs, top_logprobs, seed, parallel_tool_calls, service_tier.
• Reasoning: используется reasoning_effort вместо объекта reasoning (см. Reasoning & Effort).

Дополнительные параметры

Используйте extra_params (SDK) или передавайте напрямую в теле запроса (Gateway) для специфичных для Perplexity полей search и конфигурации:

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar",
    "messages": [{"role": "user", "content": "What is the latest news?"}],
    "search_mode": "web",
    "language_preference": "en",
    "return_images": true,
    "return_related_questions": true,
    "disable_search": false,
    "search_domain_filter": ["news.example.com"],
    "search_recency_filter": "week"
  }'

Параметры поиска

Медиа-параметры

Web Search Options

Тонкая настройка поведения поиска, в том числе по геолокации:

{
  "web_search_options": [
    {
      "search_context_size": "high",
      "user_location": {
        "latitude": 40.7128,
        "longitude": -74.0060,
        "city": "New York",
        "country": "US",
        "region": "NY"
      },
      "image_search_relevance_enhanced": true
    }
  ]
}

Reasoning & Effort

Маппинг параметров

• reasoning.effort → reasoning_effort.
• Поддерживаемые значения effort: "low", "medium", "high".
• Особая конвертация: "minimal" → "low" (Perplexity нормализует значения до low/medium/high).
• reasoning.max_tokens тихо отбрасывается (Perplexity не поддерживает управление бюджетом токенов).

Пример

// Запрос
{"reasoning": {"effort": "high"}}

// Преобразование для Perplexity
{"reasoning_effort": "high"}

// Особый случай: effort = "minimal"
{"reasoning": {"effort": "minimal"}}
→ {"reasoning_effort": "low"}

Преобразование ответа

Включение результатов поиска

Ответы Perplexity содержат дополнительные поля, связанные с интегрированным поиском:

• citations[] — цитаты источников из поиска.
• search_results[] — полные результаты поиска с метаданными.
• videos[] — видео-результаты из поиска.

Эти поля сохраняются в ответе Meridian для использования на стороне клиента.

Детализация usage

Расширенный учёт usage, специфичный для Perplexity:

Пример ответа

{
  "id": "...",
  "choices": [...],
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 150,
    "total_tokens": 250,
    "completion_tokens_details": {
      "citation_tokens": 25,
      "num_search_queries": 3,
      "reasoning_tokens": 40
    },
    "cost": { "prompt_cost": 0.001, "completion_cost": 0.002 }
  },
  "citations": ["https://example.com/article1", "https://example.com/article2"],
  "search_results": [
    {
      "title": "...",
      "url": "...",
      "snippet": "...",
      "date": "2025-01-15"
    }
  ],
  "videos": [
    {
      "title": "...",
      "url": "...",
      "duration": 300
    }
  ]
}

Стриминг

Perplexity использует OpenAI-совместимый формат стриминга. Последовательность событий:

• События chat.completion.chunk с delta-обновлениями.
• Стандартный маппинг finish reason из OpenAI.

Нюансы реализации

2. Responses API

Responses API адаптируется для Perplexity: внутри конвертируется в формат Chat Completions, а результат возвращается в формате Responses.

Параметры запроса

Маппинг параметров

Дополнительные параметры

Те же специфичные для Perplexity параметры search и конфигурации, что и в Chat Completions (см. Дополнительные параметры).

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar",
    "instructions": "You are a helpful assistant with web search capabilities",
    "input": "What is the latest news in technology?",
    "search_mode": "news",
    "return_images": true
  }'

Детали конвертации

• instructions становится system-сообщением, добавляемым в начало input-сообщений.
• input (строка или массив) конвертируется в user-сообщение(я).
• Ответ преобразуется в формат Responses API с сохранением тех же search results и расширенной детализации usage.

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

Аналогичен Chat Completions: сохраняются search results, цитаты и расширенный учёт usage.

Стриминг

Стриминг Responses использует тот же OpenAI-совместимый протокол, что и Chat Completions, с адаптацией событий под формат Responses API.