DeepSeek Harness LLM Adapter: подключение любой модели

Поставщики моделей не ограничиваются DeepSeek. Если вы хотите подключить dsh к своей конечной точке модели, вам нужно написать LLM-адаптер.

В этом разделе мы рассмотрим абстрактный класс LlmAdapter, метод stream(), регистрацию маршрута и конфигурацию cordis.yml.


Что такое LLM-адаптер?

LLM-адаптер — это класс, который наследуется от LlmAdapter и реализует метод stream().

Он преобразует не зависящие от провайдера запросы Harness в вызовы API для конкретного провайдера.

Затем он преобразует ответ обратно в фрагменты Harness, а именно StreamChunk.

Следовательно, agent-loop использует единый интерфейс и не заботится о том, какой API провайдера стоит за ним.

LLM 适配器 seam 图

На верхнем уровне находится agent-loop, который использует не зависящий от провайдера сервис потоковой генерации.

В середине находится реестр ctx.llm, который поддерживает абстрактный контракт LlmAdapter.

Внизу находятся отдельные адаптеры, каждый из которых подключается к своему формату API.

Используется при регистрацииctx.llm.registerAdapter(['my-provider'], adapter)Привязка маршрута.


Минимальная реализация

Официальная документация даёт минимальный каркас; мы следуем ему и добавляем комментарии.

stream() — это ядро, возвращающее асинхронный генератор AsyncIterable.

Комментарии из трёх шагов обозначают стандартный поток: преобразование формата сообщения, вызов потокового API и преобразование ответа в StreamChunk.

Пример

// Путь к файлу: src/my-llm-adapter.ts
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'
import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'

// Адаптер: наследует абстрактный класс и реализует stream().
class MyAdapter extends LlmAdapter {
  private apiKey: string

  constructor(apiKey: string) {
    super()
    this.apiKey = apiKey
  }

  // stream() возвращает асинхронный генератор, выдающий StreamChunk по частям
  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
    // 1. Преобразовать options.messages в формат провайдера.
    // 2. Вызвать потоковый API.
    // 3. Преобразовать ответ в значения StreamChunk.
  }
}

// Конфигурация плагина: apiKey и providers обязательны.
export interface Config {
  apiKey: string
  providers: string[]
}

// Схема Schemastery с тем же именем, проверять конфигурацию при загрузке
export const Config: Schema<Config> = Schema.объект({
  apiKey: Schema.string().required(),
  providers: Schema.array(Schema.string()).required(),
})

export const name = 'my-llm-adapter'
// Объявить зависимость от сервиса llm, чтобы гарантировать, что ctx.llm готов.
export const inject = ['llm']

export function apply(ctx: Context, config: Config) {
  const adapter = new MyAdapter(config.apiKey)
  // Привязать список маршрутов провайдера к этому адаптеру
  ctx.llm.registerAdapter(config.providers, adapter)
}

apiKey берётся из конфигурации плагина, что позволяет избежать жёсткого кодирования секрета в коде.

Массив providers объявляет, за какие маршруты провайдеров отвечает этот адаптер.

В apply сначала new MyAdapter(config.apiKey), затем registerAdapter завершает Register.

inject: ['llm'] гарантирует, что apply выполняется только после того, как служба ctx.llm будет готова.

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

В следующей статье будет подробно объяснён протокол разбиения на чанки StreamChunk.


GenerateOptions: что получает адаптер

stream() получает GenerateOptions, экспортируемый репозиторием.

Он включает модель, уровень рассуждений, историю диалога, системный промпт, схему инструментов, параметры генерации, стоп-последовательности и сигнал прерывания.

Полный набор полей определяется типами TypeScript, экспортируемыми @deepseek-ai/dsh-llm.

FieldsОписание
провайдерВыберите зарегистрированный адаптер
modelИдентификаторы моделей, принадлежащие адаптеру, не нужно регистрировать при запуске.
messagesИстория диалогов
системный промптСистемный промпт
toolsсхема инструмента
рассуждениеID уровня усилий рассуждения, поддерживаемый адаптером (необязательно).
signalСигнал прерывания, используемый отменой и освобождением ресурсов для полной остановки.

Адаптер должен сопоставлять поддерживаемые поля с конкретным API.

Если поле не может быть поддержано, следует выбросить исключение LlmError со стабильным кодом и не отбрасывать его молча.

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


Регистрация адаптера

В apply вызовите ctx.llm.registerAdapter, чтобы завершить регистрацию маршрута.

Пример

// Путь к файлу: src/my-llm-adapter.ts (фрагмент регистрации)
ctx.llm.registerAdapter(['my-provider'], adapter)

Первый параметр — список маршрутов провайдера, обрабатываемых адаптером.

GenerateOptions.provider выбирает зарегистрированный адаптер.

GenerateOptions.model передаёт ID модели, принадлежащий адаптеру; его не нужно регистрировать при запуске жизненного цикла.

Если адаптер может предоставить параметры модели селектору, он может переопределить listModels().

Когда нужно вернуть точные идентификаторы провайдера и модели, можно переопределить resolveModel(provider, model, signal?).

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

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

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

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

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

Пропуск рассуждения означает, что модель не имеет возможности задавать необязательное усилие рассуждения.


Использование в cordis.yml

Загрузите плагин адаптера вместе с agent-loop и заставьте agent-loop использовать нового провайдера и новую модель.

Пример

# Путь к файлу: cordis.yml
# Загрузить плагин адаптера; apiKey считывается из переменных окружения.
- id
: my-llm
  name
: './src/my-llm-adapter.ts'
  config
:
    apiKey
: !!js process.env.MY_API_KEY
    providers
:
     - my-provider

# Настроить agent-loop для использования провайдера и модели нового адаптера
- id
: agent-loop
  name
: '@deepseek-ai/dsh-agent-loop'
  config
:
    agents
:
      - id
: main
        provider
: my-provider
        model
: my-model-v1

config.apiKey плагина my-llm читается из переменной окружения MY_API_KEY и не записывается на диск.

Массив providers регистрирует маршрут my-provider на MyAdapter.

Настройте provider и model в agent-loop's agents.main, и сгенерированные запросы будут попадать в новый адаптер.


Практический справочник

В репозитории есть две полноценные существующие реализации для сравнения.

llm-deepseek адаптируется к DeepSeek API, используя формат, совместимый с OpenAI.

llm-pi-ai адаптирует Pi AI, который использует другой формат API.

Сравнение этих двух адаптеров показывает, как один и тот же контракт harness реализуется поверх разных SDK провайдеров.

Если сначала прочитать llm-deepseek, а затем llm-pi-ai, проще всего увидеть идею шва «контракт неизменен, реализации варьируются».


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

Итог в одном предложении: LLM-адаптер = наследовать LlmAdapter + реализовать stream() + регистрация маршрута через registerAdapter + конфигурация cordis.yml.

Вопрос для самопроверки 1: Каков возвращаемый тип stream()?

Вопрос для самопроверки 2: Что представляет собой первый параметр registerAdapter?

Вопрос для самопроверки 3: какие параметры конфигурации использует agent-loop для выбора нового адаптера?

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