Протокол StreamChunk и обработка ошибок в DeepSeek Harness

Какие данные на самом деле выводит stream() адаптера?

Ответ — StreamChunk, строго упорядоченный протокол разбиения на чанки.

Здесь рассматриваются последовательности чанков, ключевые правила и способы обработки ошибок передачи.


Протокол StreamChunk

StreamChunk — это потоковый протокол между Harness и адаптером.

Блок содержимого начинается с block-start, использует delta для инкрементальной передачи в середине и заканчивается block-end.

Текст и вызовы инструментов — это два разных типа блоков содержимого, каждый проходит через start / delta / end.

Когда все чанки завершаются, сначала отправьте usage, чтобы сообщить об использовании токенов, затем отправьте finish, чтобы объявить причину завершения.

StreamChunk 分片序列图

Диаграмма выше, сверху вниз, показывает полную последовательность чанков.

Сначала текстовый блок: block-start → text-delta × 2 → block-end.

Затем блок вызова инструмента: block-start → tool-call-delta → block-end.

Наконец, usage и finish.

Причина завершения stop указывает на нормальное завершение, а tool-calls — на запрос на выполнение инструментов.


Полная последовательность шардов

Официальная документация предоставляет exampleChunks, который создаёт все чанки из одной генерации по порядку.

text-delta можно разбить на несколько чанков, которые постепенно объединяются в полный текст.

argumentsDelta в tool-call-delta — это инкрементальная дельта исходного текста JSON.

Пример

// Путь к файлу: пример кода, демонстрирующий полную последовательность чанков
import { CallId, type StreamChunk } from '@deepseek-ai/dsh-llm'

async function* exampleChunks(): AsyncIterable<StreamChunk> {
  // 1. Начинайте каждый блок содержимого с block-start.
  // Начать текстовый блок, index равен 0
  yield { type: 'block-start', index: 0, blockType: 'text' }

  // 2. Потоковая передача текста через text-delta.
  // Дельта текста, может быть разбита на несколько фрагментов
  yield { type: 'text-delta', index: 0, text: 'example' }
  yield { type: 'text-delta', index: 0, text: ' tutorial' }

  // 3. Завершайте каждый блок содержимого с помощью block-end и полного блока.
  // Завершите полным блоком, index соответствует block-start
  yield {
    type: 'block-end',
    index: 0,
    block: { type: 'text', text: 'example tutorial' },
  }

  // 4. Блок вызова инструмента.
  // Начать блок вызова инструмента, index равен 1
  yield { type: 'block-start', index: 1, blockType: 'tool-call' }
  // Имя инструмента и дельта аргумента, id сгенерирован фабрикой CallId
  yield {
    type: 'tool-call-delta',
    index: 1,
    id: CallId('call-123'),
    name: 'bash',
    argumentsDelta: '{"command":"echo example"}',
  }
  // Завершить полным блоком, arguments — собранный текст JSON
  yield {
    type: 'block-end',
    index: 1,
    block: {
      type: 'tool-call',
      id: CallId('call-123'),
      name: 'bash',
      arguments: '{"command":"echo example"}',
    },
  }

  // 5. Использование токенов.
  // Сообщить об использовании токенов, должно быть до finish.
  yield { type: 'usage', usage: { inputTokens: 100, outputTokens: 50 } }

  // 6. Причина завершения.
  // Последний чанк, укажите причину завершения.
  yield { type: 'finish', reason: { kind: 'stop' } }
  // В качестве альтернативы, { kind: 'tool-calls' } запрашивает выполнение инструмента.
}

CallId — это фабричная функция, встроенная в протокол, используемая для генерации идентификаторов вызовов инструментов.

argumentsDelta может быть полностью сгенерирован в одном чанке или инкрементально сгенерирован в нескольких чанках.


Ключевые правила

В протоколе есть пять жёстких правил; нарушение любого из них приведёт к тому, что потребитель не сможет выполнить парсинг.

ПравилаОписание
block-start и block-end образуют пару.У каждого block-start должен быть соответствующий block-end.
Значение index увеличивается с 0.Используется для определения порядка блоков содержимого.
argumentsDelta — это необработанная JSON-дельта.Может быть полностью сгенерировано в одном чанке или сгенерировано по нескольким чанкам
finish должен быть последним чанкомПосле этого дальнейшие шарды не допускаются.
usage должен идти перед finish.Сначала сообщите об использовании токенов, затем объявите об окончании

И text-delta, и tool-call-delta должны содержать index своего блока-владельца, а блоки содержимого не должны чередоваться друг с другом.


Обработка ошибок: выражайте сбои через LlmError

Адаптер должен выбрасывать ошибки передачи и протокола через LlmError со стабильным кодом.

agent-loop сохраняет ошибку и её код для диагностики и обработки политик.

Не полагайтесь на то, что обычный Error будет автоматически преобразован.

Стабильный код позволяет верхнему слою точно сопоставлять типы ошибок вместо разбора строк ошибок.

Каждый HTTP-запрос провайдера также должен объединять attributionHeaders().

Также передавайте options.signal в fetch, чтобы отмена и освобождение ресурсов приводили к полной остановке.

Пример

// Путь к файлу: пример кода, скелет HttpAdapter с обработкой ошибок
import {
  attributionHeaders,
  LlmAdapter,
  LlmError,
  type GenerateOptions,
  type StreamChunk,
} from '@deepseek-ai/dsh-llm'

class HttpAdapter extends LlmAdapter {
  // Конструктор внедряет адрес конечной точки
  constructor(private readonly endpoint: string) {
    super()
  }

  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
    // Инициировать HTTP-запрос, объединить заголовки атрибуции, передать сигнал прерывания.
    const response = await fetch(this.endpoint, {
      method: 'POST',
      headers: {
        'content-type': 'application/json',
        ...attributionHeaders(),
      },
      body: JSON.stringify({ model: options.model, messages: options.messages }),
      // Когда вызывающий запрашивает отмену, fetch немедленно прервётся
      ...options.signal ? { signal: options.signal } : {},
    })
    if (!response.ok) {
      // Используйте LlmError со стабильным кодом для обозначения сбоя транспорта
      throw new LlmError(`Ошибка API провайдера: ${response.status}`, 'PROVIDER_HTTP_ERROR')
    }
    // Настоящий адаптер разбирает ответ и выдаёт полную последовательность чанков.
    // Настоящий адаптер разбирает тело ответа здесь, создавая полную последовательность чанков.
    yield { type: 'finish', reason: { kind: 'stop' } }
  }
}

attributionHeaders() включает информацию об атрибуции в заголовки запроса.

Когда options.signal присутствует, передайте его как signal в fetch и немедленно остановитесь, когда запрос отменён.

Когда response.ok имеет значение false, выбросьте LlmError с кодом PROVIDER_HTTP_ERROR.

Скелет только выдаёт finish; настоящий адаптер разбирал бы тело ответа здесь.

Первый аргумент LlmError — это сообщение, а второй аргумент — стабильный код.

Верхний уровень принимает решения о политике на основе кода, поэтому, как только код опубликован, не меняйте его.


Поля, которые нельзя молча отбрасывать.

Если GenerateOptions содержит поля, которые адаптер не может поддерживать, также выбросьте LlmError; не отбрасывайте их молча.

Метаданные рассуждений включают упорядоченный непрозрачный ID, отображаемое имя и необязательные значения конфигурации по умолчанию.

Пожалуйста, сохраняйте авторитетный список необязательных значений, предоставленный адаптером, включая значения off, возвращаемые его вышестоящим API возможностей.

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

Сервис проверит агрегированный результат и отклонит явно указанные, но неподдерживаемые уровни интенсивности рассуждений перед вызовом stream().

Если reasoning не указан, это означает, что модель не обладает необязательной возможностью интенсивности рассуждений.


Итог и самопроверка

Краткое описание в одном предложении: протокол StreamChunk использует парные блоки для описания содержимого, завершается блоками usage и finish; при сбое он выражается через LlmError, несущий стабильный код.

Вопрос для самопроверки 1: Какой минимальный набор чанков нужен текстовому блоку?

Вопрос для самопроверки 2: Каков порядок usage и finish?

Вопрос для самопроверки 3: Когда запрос завершается неудачно, почему следует использовать LlmError с кодом вместо обычного Error?

Другие расширения