DeepSeek Harness LLM Adapter: подключение любой модели
Поставщики моделей не ограничиваются DeepSeek. Если вы хотите подключить dsh к своей конечной точке модели, вам нужно написать LLM-адаптер.
В этом разделе мы рассмотрим абстрактный класс LlmAdapter, метод stream(), регистрацию маршрута и конфигурацию cordis.yml.
Что такое LLM-адаптер?
LLM-адаптер — это класс, который наследуется от LlmAdapter и реализует метод stream().
Он преобразует не зависящие от провайдера запросы Harness в вызовы API для конкретного провайдера.
Затем он преобразует ответ обратно в фрагменты Harness, а именно StreamChunk.
Следовательно, agent-loop использует единый интерфейс и не заботится о том, какой API провайдера стоит за ним.
На верхнем уровне находится agent-loop, который использует не зависящий от провайдера сервис потоковой генерации.
В середине находится реестр ctx.llm, который поддерживает абстрактный контракт LlmAdapter.
Внизу находятся отдельные адаптеры, каждый из которых подключается к своему формату API.
Используется при регистрацииctx.llm.registerAdapter(['my-provider'], adapter)Привязка маршрута.
Минимальная реализация
Официальная документация даёт минимальный каркас; мы следуем ему и добавляем комментарии.
stream() — это ядро, возвращающее асинхронный генератор AsyncIterable.
Комментарии из трёх шагов обозначают стандартный поток: преобразование формата сообщения, вызов потокового API и преобразование ответа в StreamChunk.
Пример
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, чтобы завершить регистрацию маршрута.
Пример
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 использовать нового провайдера и новую модель.
Пример
# Загрузить плагин адаптера; 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 для выбора нового адаптера?
Другие расширения