Блоки контента результатов поиска в настоящее время находятся в бета-версии. Используйте бета-заголовок search-results-2025-06-09 для включения этой функции.

Блоки контента результатов поиска обеспечивают естественные цитирования с правильной атрибуцией источников, привнося качество цитирований веб-поиска в ваши пользовательские приложения. Эта функция особенно мощна для RAG (Retrieval-Augmented Generation) приложений, где вам нужно, чтобы Claude точно цитировал источники.

​
Ключевые преимущества

  • Естественные цитирования - Достигайте того же качества цитирований, что и веб-поиск, для любого контента
  • Гибкая интеграция - Используйте в возвращаемых значениях инструментов для динамического RAG или как контент верхнего уровня для предварительно загруженных данных
  • Правильная атрибуция источников - Каждый результат включает информацию об источнике и заголовке для четкой атрибуции
  • Не нужны обходные пути с документами - Устраняет необходимость в обходных путях на основе документов
  • Согласованный формат цитирований - Соответствует качеству и формату цитирований функции веб-поиска Claude

​
Как это работает

Результаты поиска могут быть предоставлены двумя способами:

  1. Из вызовов инструментов - Ваши пользовательские инструменты возвращают результаты поиска, обеспечивая динамические RAG-приложения
  2. Как контент верхнего уровня - Вы предоставляете результаты поиска напрямую в пользовательских сообщениях для предварительно загруженного или кэшированного контента

В обоих случаях Claude может автоматически цитировать информацию из результатов поиска с правильной атрибуцией источников.

​
Схема результата поиска

Результаты поиска используют следующую структуру:

{
  "type": "search_result",
  "source": "https://example.com/article",  // Обязательно: URL источника или идентификатор
  "title": "Заголовок статьи",                  // Обязательно: Заголовок результата
  "content": [ // Обязательно: Массив текстовых блоков
    {
      "type": "text",
      "text": "Фактическое содержимое результата поиска..."
    }
  ],
  "citations": {                             // Необязательно: Конфигурация цитирований
    "enabled": true                          // Включить/отключить цитирования для этого результата
  }
}

​
Обязательные поля

ПолеТипОписание
typestringДолжно быть "search_result"
sourcestringURL источника или идентификатор для контента
titlestringОписательный заголовок для результата поиска
contentarrayМассив текстовых блоков, содержащих фактический контент

​
Необязательные поля

ПолеТипОписание
citationsobjectКонфигурация цитирований с булевым полем enabled
cache_controlobjectНастройки управления кэшем (например, {"type": "ephemeral"})

Каждый элемент в массиве content должен быть текстовым блоком с:

  • type: Должно быть "text"
  • text: Фактическое текстовое содержимое (непустая строка)

​
Метод 1: Результаты поиска из вызовов инструментов

Наиболее мощный случай использования - это возврат результатов поиска из ваших пользовательских инструментов. Это обеспечивает динамические RAG-приложения, где инструменты извлекают и возвращают релевантный контент с автоматическими цитированиями.

​
Пример: Инструмент базы знаний

from anthropic import Anthropic
from anthropic.types.beta import (
    BetaMessageParam,
    BetaTextBlockParam,
    BetaSearchResultBlockParam,
    BetaToolResultBlockParam
)

client = Anthropic()

# Определяем инструмент поиска по базе знаний
knowledge_base_tool = {
    "name": "search_knowledge_base",
    "description": "Поиск в корпоративной базе знаний для получения информации",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Поисковый запрос"
            }
        },
        "required": ["query"]
    }
}

# Функция для обработки вызова инструмента
def search_knowledge_base(query):
    # Ваша логика поиска здесь
    # Возвращает результаты поиска в правильном формате
    return [
        BetaSearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/product-guide",
            title="Руководство по настройке продукта",
            content=[
                BetaTextBlockParam(
                    type="text",
                    text="Для настройки продукта перейдите в Настройки > Конфигурация. Таймаут по умолчанию составляет 30 секунд, но может быть настроен в диапазоне от 10 до 120 секунд в зависимости от ваших потребностей."
                )
            ],
            citations={"enabled": True}
        ),
        BetaSearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/troubleshooting",
            title="Руководство по устранению неполадок",
            content=[
                BetaTextBlockParam(
                    type="text",
                    text="Если вы сталкиваетесь с ошибками таймаута, сначала проверьте настройки конфигурации. Распространенные причины включают задержку сети и неправильные значения таймаута."
                )
            ],
            citations={"enabled": True}
        )
    ]

# Создаем сообщение с инструментом
response = client.beta.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    betas=["search-results-2025-06-09"],
    tools=[knowledge_base_tool],
    messages=[
        BetaMessageParam(
            role="user",
            content="Как настроить параметры таймаута?"
        )
    ]
)

# Когда Claude вызывает инструмент, предоставляем результаты поиска
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])
    
    # Отправляем результат инструмента обратно
    final_response = client.beta.messages.create(
        model="claude-opus-4-20250514",
        max_tokens=1024,
        betas=["search-results-2025-06-09"],
        messages=[
            BetaMessageParam(role="user", content="Как настроить параметры таймаута?"),
            BetaMessageParam(role="assistant", content=response.content),
            BetaMessageParam(
                role="user",
                content=[
                    BetaToolResultBlockParam(
                        type="tool_result",
                        tool_use_id=response.content[0].id,
                        content=tool_result  # Результаты поиска идут сюда
                    )
                ]
            )
        ]
    )

​
Метод 2: Результаты поиска как контент верхнего уровня

Вы также можете предоставлять результаты поиска напрямую в пользовательских сообщениях. Это полезно для:

  • Предварительно загруженного контента из вашей поисковой инфраструктуры
  • Кэшированных результатов поиска из предыдущих запросов
  • Контента из внешних поисковых сервисов
  • Тестирования и разработки

​
Пример: Прямые результаты поиска

from anthropic import Anthropic
from anthropic.types.beta import (
    BetaMessageParam,
    BetaTextBlockParam,
    BetaSearchResultBlockParam
)

client = Anthropic()

# Предоставляем результаты поиска напрямую в пользовательском сообщении
response = client.beta.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    betas=["search-results-2025-06-09"],
    messages=[
        BetaMessageParam(
            role="user",
            content=[
                BetaSearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/api-reference",
                    title="Справочник API - Аутентификация",
                    content=[
                        BetaTextBlockParam(
                            type="text",
                            text="Все API-запросы должны включать API-ключ в заголовке Authorization. Ключи можно сгенерировать из панели управления. Ограничения скорости: 1000 запросов в час для стандартного уровня, 10000 для премиум."
                        )
                    ],
                    citations={"enabled": True}
                ),
                BetaSearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/quickstart",
                    title="Руководство по началу работы",
                    content=[
                        BetaTextBlockParam(
                            type="text",
                            text="Чтобы начать: 1) Зарегистрируйте аккаунт, 2) Сгенерируйте API-ключ из панели управления, 3) Установите наш SDK с помощью pip install company-sdk, 4) Инициализируйте клиент с вашим API-ключом."
                        )
                    ],
                    citations={"enabled": True}
                ),
                BetaTextBlockParam(
                    type="text",
                    text="На основе этих результатов поиска, как мне аутентифицировать API-запросы и каковы ограничения скорости?"
                )
            ]
        )
    ]
)

print(response.model_dump_json(indent=2))

​
Ответ Claude с цитированиями

Независимо от того, как предоставляются результаты поиска, Claude автоматически включает цитирования при использовании информации из них:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Для аутентификации API-запросов вам нужно включить API-ключ в заголовок Authorization",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Справочник API - Аутентификация",
          "cited_text": "Все API-запросы должны включать API-ключ в заголовке Authorization",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Вы можете сгенерировать API-ключи из вашей панели управления",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Справочник API - Аутентификация",
          "cited_text": "Ключи можно сгенерировать из панели управления",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Ограничения скорости составляют 1000 запросов в час для стандартного уровня и 10000 запросов в час для премиум уровня.",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Справочник API - Аутентификация",
          "cited_text": "Ограничения скорости: 1000 запросов в час для стандартного уровня, 10000 для премиум",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    }
  ]
}

​
Поля цитирования

Каждое цитирование включает:

ПолеТипОписание
typestringВсегда "search_result_location" для цитирований результатов поиска
sourcestringИсточник из исходного результата поиска
titlestring или nullЗаголовок из исходного результата поиска
cited_textstringТочный текст, который цитируется
search_result_indexintegerИндекс результата поиска (начиная с 0)
start_block_indexintegerНачальная позиция в массиве content
end_block_indexintegerКонечная позиция в массиве content

Примечание: search_result_index относится к индексу блока контента результата поиска (начиная с 0), независимо от того, как были предоставлены результаты поиска (вызов инструмента или контент верхнего уровня).

​
Множественные блоки контента

Результаты поиска могут содержать несколько текстовых блоков в массиве content:

{
  "type": "search_result",
  "source": "https://docs.company.com/api-guide",
  "title": "Документация API",
  "content": [
    {
      "type": "text",
      "text": "Аутентификация: Все API-запросы требуют API-ключ."
    },
    {
      "type": "text",
      "text": "Ограничения скорости: API позволяет 1000 запросов в час на ключ."
    },
    {
      "type": "text",
      "text": "Обработка ошибок: API возвращает стандартные HTTP-коды состояния."
    }
  ]
}

Claude может цитировать конкретные блоки, используя поля start_block_index и end_block_index.

​
Расширенное использование

​
Комбинирование обоих методов

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

# Первое сообщение с результатами поиска верхнего уровня
messages = [
    BetaMessageParam(
        role="user",
        content=[
            BetaSearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="Обзор продукта",
                content=[
                    BetaTextBlockParam(type="text", text="Наш продукт помогает командам сотрудничать...")
                ],
                citations={"enabled": True}
            ),
            BetaTextBlockParam(
                type="text",
                text="Расскажите мне об этом продукте и найдите информацию о ценах"
            )
        ]
    )
]

# Claude может ответить и вызвать инструмент для поиска цен
# Затем вы предоставляете результаты инструмента с дополнительными результатами поиска

​
Комбинирование с другими типами контента

Оба метода поддерживают смешивание результатов поиска с другим контентом:

# В результатах инструмента
tool_result = [
    BetaSearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="Руководство пользователя",
        content=[BetaTextBlockParam(type="text", text="Детали конфигурации...")],
        citations={"enabled": True}
    ),
    BetaTextBlockParam(
        type="text",
        text="Дополнительный контекст: Это применимо к версии 2.0 и более поздним."
    )
]

# В контенте верхнего уровня
user_content = [
    BetaSearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="Исследовательская статья",
        content=[BetaTextBlockParam(type="text", text="Ключевые выводы...")],
        citations={"enabled": True}
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"}
    },
    BetaTextBlockParam(
        type="text",
        text="Как график связан с результатами исследования?"
    )
]

​
Управление кэшем

Добавьте управление кэшем для лучшей производительности:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "Руководство пользователя",
  "content": [{"type": "text", "text": "..."}],
  "cache_control": {
    "type": "ephemeral"
  }
}

​
Управление цитированиями

По умолчанию цитирования отключены для результатов поиска. Вы можете включить цитирования, явно установив конфигурацию citations:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "Руководство пользователя",
  "content": [{"type": "text", "text": "Важная документация..."}],
  "citations": {
    "enabled": true  // Включить цитирования для этого результата
  }
}

Когда citations.enabled установлено в true, Claude будет включать ссылки на цитирования при использовании информации из результата поиска. Это обеспечивает:

  • Естественные цитирования для ваших пользовательских RAG-приложений
  • Атрибуцию источников при взаимодействии с проприетарными базами знаний
  • Качество цитирований веб-поиска для любого пользовательского инструмента, который возвращает результаты поиска

Если поле citations опущено, цитирования отключены по умолчанию.

Цитирования работают по принципу “все или ничего”: либо все результаты поиска в запросе должны иметь включенные цитирования, либо все должны иметь их отключенными. Смешивание результатов поиска с разными настройками цитирований приведет к ошибке. Если вам нужно отключить цитирования для некоторых источников, вы должны отключить их для всех результатов поиска в этом запросе.

​
Лучшие практики

​
Для поиска на основе инструментов (Метод 1)

  • Динамический контент: Используйте для поиска в реальном времени и динамических RAG-приложений
  • Обработка ошибок: Возвращайте соответствующие сообщения при неудачных поисках
  • Ограничения результатов: Возвращайте только наиболее релевантные результаты, чтобы избежать переполнения контекста

​
Для поиска верхнего уровня (Метод 2)

  • Предварительно загруженный контент: Используйте, когда у вас уже есть результаты поиска
  • Пакетная обработка: Идеально для обработки нескольких результатов поиска одновременно
  • Тестирование: Отлично подходит для тестирования поведения цитирований с известным контентом

​
Общие лучшие практики

  1. Эффективно структурируйте результаты

    • Используйте четкие, постоянные URL источников
    • Предоставляйте описательные заголовки
    • Разбивайте длинный контент на логические текстовые блоки

  2. Поддерживайте согласованность

    • Используйте согласованные форматы источников в вашем приложении
    • Убедитесь, что заголовки точно отражают контент
    • Поддерживайте согласованное форматирование

  3. Грациозно обрабатывайте ошибки

    def search_with_fallback(query):
    try:
        results = perform_search(query)
        if not results:
            return {"type": "text", "text": "Результаты не найдены."}
        return format_as_search_results(results)
    except Exception as e:
        return {"type": "text", "text": f"Ошибка поиска: {str(e)}"}

​
Ограничения

  • Блоки контента результатов поиска доступны только с бета-заголовком
  • Поддерживается только текстовый контент внутри результатов поиска (никаких изображений или других медиа)
  • Массив content должен содержать как минимум один текстовый блок