Продвинутый

DeepSeek Harness: плагинная архитектура для AI-агентов

Алексей Кузнецов
Алексей Кузнецов
Системный администратор3 ноября 2026 г.13 мин чтения

DeepSeek Harness превращает компоненты в плагины, упрощая интеграцию AI-моделей и инструментов. Рассказываем об архитектуре, настройке и возможностях расшире...

DeepSeek Harness: плагинная архитектура для AI-агентов

DeepSeek Harness превращает компоненты в плагины, упрощая интеграцию AI-моделей и инструментов. Рассказываем об архитектуре, настройке и возможностях расширения.

Что такое DeepSeek Harness

DeepSeek Harness: плагинная архитектура для AI-агентов

Что такое DeepSeek Harness

DeepSeek Harness — это фреймворк, который превращает AI-модели и инструменты в плагины, упрощающие их интеграцию в единую систему. Вместо того чтобы писать отдельные скрипты для каждой задачи, вы подключаете готовые компоненты как плагины — так же, как вы устанавливаете расширения в браузере.

Представьте, что у вас есть набор инструментов: модель для генерации текста, плагин для работы с базой данных, утилита для парсинга веб-страниц. Harness позволяет вам объединить их в одну систему, где каждый компонент работает как самостоятельный плагин, но взаимодействует с остальными через единый интерфейс.

Архитектура на основе плагинов

Core архитектура Harness построена на принципе "плагина-как-сервиса". Каждый плагин — это автономный компонент, который:

  • Экспонирует интерфейс через gRPC или HTTP
  • Имеет собственный конфигурационный файл в YAML формате
  • Регистрируется в реестре плагинов при запуске
  • Обменивается данными через стандартный формат сообщений
yaml
# plugins/deepseek-model.yaml
name: deepseek-model
version: "1.2.0"
type: model
entry_point: deepseek_plugin.py
description: Модель DeepSeek для генерации текста
config:
  api_endpoint: "https://api.deepseek.com"
  model_name: "deepseek-coder"
  max_tokens: 2048
  temperature: 0.7

Плагин подключается к системе через специальный декоратор:

python
# plugins/deepseek_plugin.py
from deepseek_harness import register_plugin

@register_plugin
class DeepSeekPlugin:
    def __init__(self, config):
        self.endpoint = config['api_endpoint']
        self.model = config['model_name']
    
    async def generate(self, prompt, context=None):
        # Реализация запроса к API
        response = await self._call_api(prompt)
        return response['text']

Реестр плагинов поддерживает динамическую загрузку — вы можете добавлять новые плагины без перезапуска всей системы. Это особенно полезно при разработке AI-агентов, где часто требуется быстро протестировать новую модель или инструмент.

Установка и быстрая настройка

Для начала работы с DeepSeek Harness достаточно выполнить три шага:

  1. Установите Harness и зависимые компоненты
bash
# Установка через pip
pip install deepseek-harness

# Установка необходимых плагинов
pip install deepseek-plugin openai-plugin database-plugin
  1. Создайте базовую конфигурацию
yaml
# config.yaml
plugins:
  - name: deepseek-model
    path: plugins/deepseek_plugin.py
    config:
      api_endpoint: "https://api.deepseek.com"
      model_name: "deepseek-coder"
  
  - name: text-parser
    path: plugins/parser_plugin.py
    config:
      max_length: 5000
  
  - name: database-connector
    path: plugins/db_plugin.py
    config:
      connection_string: "postgresql://user:pass@localhost/ai_db"

agent:
  name: "test-agent"
  model: "deepseek-model"
  tools: ["text-parser", "database-connector"]
  1. Запустите агент
bash
# Запуск агента с конфигурацией
python -m deepseek_harness run --config config.yaml

# Проверка состояния плагинов
python -m deepseek_harness status

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

bash
# Режим разработки с горячей перезагрузкой
python -m deepseek_harness dev --config config.yaml

Для продакшн-окружения рекомендуется использовать Docker:

dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
CMD ["python", "-m", "deepseek_harness", "run", "--config", "config.yaml"]

Готовый Docker-образ можно собрать и запустить:

bash
docker build -t deepseek-harness .
docker run -v $(pwd)/config.yaml:/app/config.yaml deepseek-harness

Возможности расширения

DeepSeek Harness поддерживает несколько типов плагинов:

  • Модельные плагины — для работы с LLM (DeepSeek, OpenAI, Claude)
  • Инструментальные плагины — для парсинга, анализа, преобразования данных
  • Хранилищные плагины — для работы с базами данных и файловыми системами
  • Сетевые плагины — для HTTP-запросов и WebSocket-соединений

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

Полезные ссылки

Как работают плагины

Механизм загрузки плагинов

DeepSeek Harness использует директорию плагинов (plugins/) в корне проекта. Система автоматически обнаруживает модули по файлу plugin.json в каждой директории:

bash
# Структура директории плагина
plugins/
├── my-model/
│   ├── plugin.json
│   ├── __init__.py
│   └── model.py
├── search-tool/
│   ├── plugin.json
│   ├── __init__.py
│   └── search.py
└── utils/
    ├── plugin.json
    ├── __init__.py
    └── helpers.py

Файл plugin.json определяет метаданные:

json
{
  "name": "my-model",
  "version": "1.2.0",
  "type": "model",
  "entry": "model.py",
  "description": "Интеграция с LLM-моделью MyModel"
}

Загрузка происходит через plugin_loader.py, который сканирует директорию, импортирует плагин и регистрирует его в центральном реестре:

python
# plugin_loader.py
def load_plugins(plugin_dir="plugins/"):
    registry = {}
    for plugin_path in Path(plugin_dir).iterdir():
        if not plugin_path.is_dir():
            continue
            
        manifest = json.loads((plugin_path / "plugin.json").read_text())
        module_name = manifest["entry"].replace(".py", "")
        
        spec = importlib.util.spec_from_file_location(
            f"{manifest['name']}.{module_name}",
            plugin_path / f"{module_name}.py"
        )
        module = importlib.util.module_from_spec(spec)
        sys.modules[spec.name] = module
        spec.loader.exec_module(module)
        
        registry[manifest["name"]] = {
            "manifest": manifest,
            "module": module
        }
    
    return registry

Автоматическая перезагрузка работает через watchdog:

bash
# Установка зависимостей для слежения за изменениями
pip install watchdog

# Запуск загрузчика с отслеживанием изменений
python -m plugins.loader --watch plugins/

Разработка пользовательских плагинов

Для создания нового плагина сначала определите тип (model, tool, utility) и точку расширения:

json
{
  "name": "custom-tool",
  "version": "0.1.0",
  "type": "tool",
  "entry": "tool.py",
  "description": "Пользовательский инструмент для работы с CSV",
  "extension_point": "data_processor",
  "dependencies": {
    "pandas": ">=2.0.0"
  }
}

Основной файл плагина реализует интерфейс IPlugin:

python
# plugins/custom-tool/tool.py
from interfaces import IPlugin
from typing import Dict, Any

class CustomToolPlugin(IPlugin):
    def __init__(self, config: Dict[str, Any]):
        self.config = config
        self.name = "custom-tool"
    
    def execute(self, payload: Dict[str, Any]) -> Dict[str, Any]:
        """Обработка CSV с использованием pandas"""
        import pandas as pd
        
        df = pd.read_csv(self.config["input_file"])
        
        if self.config.get("transform"):
            if self.config["transform"] == "normalize":
                for col in df.select_dtypes(include=['float64', 'int64']).columns:
                    df[col] = (df[col] - df[col].min()) / (df[col].max() - df[col].min())
        
        output_path = self.config.get("output_file", "output.csv")
        df.to_csv(output_path, index=False)
        
        return {
            "status": "success",
            "rows_processed": len(df),
            "output_file": output_path
        }
    
    def health_check(self) -> bool:
        """Проверка работоспособности плагина"""
        return True

Конфигурация плагина в config.yaml:

yaml
plugins:
  custom-tool:
    input_file: "data/input.csv"
    transform: "normalize"
    output_file: "data/processed.csv"
    parallel: true
    max_workers: 4

Регистрация плагина в центральной конфигурации:

bash
# Команда для регистрации нового плагина
python -m plugins.register custom-tool \
  --config config.yaml \
  --type tool \
  --extension-point data_processor

Пример интеграции с другими плагинами через plugin_bus.py:

python
# plugins/plugin_bus.py
class PluginBus:
    def __init__(self, registry):
        self.registry = registry
        self.event_bus = EventBus()
    
    def send_event(self, event_type: str, data: Dict[str, Any]):
        """Отправка события всем заинтересованным плагинам"""
        for plugin_name, plugin_info in self.registry.items():
            if hasattr(plugin_info["module"], "handle_event"):
                try:
                    plugin_info["module"].handle_event(event_type, data)
                except Exception as e:
                    print(f"Plugin {plugin_name} error: {e}")
    
    def get_plugin(self, name: str):
        """Получение плагина по имени"""
        return self.registry.get(name, {}).get("module")

Типичные ошибки при разработке плагинов:

  1. Отсутствие plugin.json — система не обнаружит модуль
  2. Неправильный entry — загрузчик не сможет импортировать модуль
  3. Отсутствие health_check() — мониторинг не будет работать корректно

Полезные команды для работы с плагинами:

bash
# Проверка списка загруженных плагинов
python -m plugins.list

# Тестирование плагина локально
python -m plugins.test custom-tool --payload '{"input_file": "test.csv"}'

# Отключение плагина
python -m plugins.disable custom-tool

# Включение плагина
python -m plugins.enable custom-tool

Полную документацию по архитектуре и API можно найти в статье DeepSeek Harness: Плагинная архитектура для AI-агентов, а примеры реализации — в коллекции .agents реальных инженеров.

Интеграция с AI-агентами и инструментами

Интеграция с AI-агентами и инструментами

Подключение к LLM-моделям

Для любого AI-агента основой является модель, к которой он обращается. DeepSeek Harness делает этот процесс предсказуемым и повторяемым — компоненты модели становятся плагинами, которые можно подключать по мере необходимости.

Пример: загрузка модели Llama 3 через плагин

yaml
# dsh.yaml
models:
  - name: llama3
    plugin: dsh-plugin-llama
    path: /opt/models/llama3
    params:
      tensor_parallel_size: 1
      max_batch_size: 32

Команда для добавления плагина:

bash
dsh plugin install dsh-plugin-llama
dsh model add llama3 --plugin dsh-plugin-llama --path /opt/models/llama3

С практической точки зрения, после установки плагина модель появляется в списке доступных агентов без перезапуска всей среды. Это сравнимо с подключением нового SSD к рабочей станции — достаточно подсоединить кабель, и система видит новое хранилище.

Почему это важно

  • Предсказуемость конфигурации — один и тот же YAML-запрос всегда дает одинаковый результат.
  • Разделение обязанностей — плагин отвечает только за загрузку модели, а оркестратор управляет взаимодействием.
  • Гибкость масштабирования — можно подключать несколько плагинов моделей параллельно, как несколько графических карт в кластере.

Если мы посмотрим на реальный кейс: в домашней лаборатории Алексея серверы Vinnie-Pugh и Piggy используют один и тот же плагин модели, но с разными параметрами тензорной параллелизации для задач генерации текста и чат-ботов.

Работа с плагинами agentic-воркфлоу

Агентские рабочие процессы часто требуют набора инструментов — файловых систем, баз данных, внешних API. В DeepSeek Harness эти инструменты также представлены плагинами, что упрощает их подключение и управление.

Пример: подключение плагина для работы с файловой системой

yaml
# dsh-workflow.yaml
workflows:
  - name: file-ops
    plugin: dsh-plugin-fs
    config:
      root: /shared/data
      read_only: false

Установка и активация плагина:

bash
dsh plugin install dsh-plugin-fs
dsh workflow enable file-ops

После активации агент может выполнять операции вложения через единый интерфейс:

python
# Пример агента, использующего плагин файловой системы
from dsh import Agent

agent = Agent()
agent.use_plugin('file-ops')
result = agent.execute('read', path='/shared/data/config.json')

С практической точки зрения, такой подход позволяет быстро добавлять новые инструменты — например, плагин для работы с базой данных PostgreSQL или API-интегратор для внешних сервисов — без изменения кода агента.

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

  • Модульность — каждый инструмент изолирован, что повышает безопасность и тестируемость.
  • Повторяемость конфигураций — один YAML-файл для всей среды, как конфигурация NAS в TrueNAS.
  • Мониторинг и алерты — плагин может отправлять метрики в Prometheus, что позволяет видеть, когда инструмент выходит из строя.

Если сравнить с реальной жизнью: это как иметь набор инструментов в мастерской — каждый инструмент находится в своем ящике, но доступен одним движением руки.


Полезные материалы

Практические примеры и кейсы использования

Практические примеры и кейсы использования

Автоматизация задач через плагины

Представьте, что вам нужно автоматически обрабатывать входящие запросы, извлекать данные из баз данных и отправлять результаты в Slack. С DeepSeek Harness это становится просто — достаточно написать два плагина и соединить их в цепочку.

yaml
# plugins/task-processor.yaml
apiVersion: dsh/v1
kind: Plugin
metadata:
  name: task-processor
  version: 0.9.0
spec:
  description: "Парсер входящих запросов с классификацией по типам задач"
  entryPoint: main.py
  dependencies:
    - requests>=2.28.0
    - pydantic>=2.0.0
  
  config:
    input_queue: "tasks.incoming"
    output_queue: "tasks.processed"
    classification_model: "bert-base-ru"

Вот как это работает на практике. Сначала плагин подписывается на входящую очередь, затем запускает классификатор и маршрутизирует задачи в соответствующие обработчики:

python
# plugins/task-processor/main.py
import asyncio
from dsh import plugin
from dsh.queues import RabbitMQQueue

@plugin.handler("classify_task")
async def classify_task(context):
    """Классифицирует задачу и маршрутизирует её"""
    message = context.message
    task_type = await classify_with_model(message.content)
    
    # Маршрутизация в зависимости от типа
    if task_type == "database":
        await context.emit("extract_data", {"query": message.content})
    elif task_type == "notification":
        await context.emit("send_slack", {"text": message.content})
    else:
        await context.emit("fallback_handler", {"text": message.content})

async def main():
    queue = RabbitMQQueue("tasks.incoming")
    await plugin.serve(queue, classify_task)

if __name__ == "__main__":
    asyncio.run(main())

Для отправки уведомлений в Slack нужен другой плагин:

yaml
# plugins/slack-notifier.yaml
apiVersion: dsh/v1
kind: Plugin
metadata:
  name: slack-notifier
  version: 1.2.0
spec:
  description: "Отправка уведомлений в Slack с форматированием"
  entryPoint: slack_bot.py
  dependencies:
    - slack-sdk>=3.19.0
  
  config:
    webhook_url: "${SLACK_WEBHOOK_URL}"
    channel: "#alerts"
    max_retries: 3

И его реализация:

python
# plugins/slack-notifier/slack_bot.py
from dsh import plugin
from slack_sdk import WebhookClient
import json

@plugin.handler("send_slack")
async def send_slack_notification(context):
    """Отправляет сообщение в Slack с повторными попытками"""
    config = context.config
    client = WebhookClient(config.webhook_url)
    
    for attempt in range(config.max_retries):
        try:
            response = client.send(
                text=context.payload["text"],
                channel=config.channel
            )
            await context.log.info(f"Уведомление отправлено: {response.ts}")
            return {"status": "sent", "timestamp": response.ts}
        except Exception as e:
            await context.log.warning(f"Попытка {attempt + 1} не удалась: {str(e)}")
            if attempt == config.max_retries - 1:
                raise
            await asyncio.sleep(2 ** attempt)  # Экспоненциальная задержка

async def main():
    await plugin.serve(config_file="config.yaml")

if __name__ == "__main__":
    asyncio.run(main())

Результат — полностью автоматизированная рабочая лошадка, которая работает 24/7 без ручного вмешательства. Конфигурация хранится отдельно от кода, что позволяет быстро менять параметры без перекомпиляции.

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

Когда у вас в кластере несколько узлов, которые выполняют плагины, важно видеть, что происходит. DeepSeek Harness поставляется с готовыми инструментами мониторинга, которые интегрируются с вашей существующей инфраструктурой.

Сначала настроим централизованный сбор логов с помощью Loki:

yaml
# monitoring/loki-config.yaml
auth_enabled: false

server:
  http_listen_port: 3100

ingester:
  max_chunk_idle: 1h
  chunk_target_size: 1048576
  chunk_idle: 5m
  
schema_config:
  configs:
    - from: 0001-01-01
      store: boltdb-shipper
      object_store: filesystem
      schema: v11
      index:
        prefix: index_
        period: 24h

storage_config:
  boltdb_shaper:
    shared_store: filesystem
  filesystem:
    directory: /tmp/loki/chunks

compactor:
  working_directory: /tmp/loki/boltdb-shipper-compactor
  shared_store: filesystem

limits_config:
  enforce_metric_name: false
  reject_old_samples: true
  reject_old_samples_max_age: 168h

Теперь подключим плагин для логирования в DeepSeek Harness:

yaml
# plugins/logger-plugin.yaml
apiVersion: dsh/v1
kind: Plugin
metadata:
  name: structured-logger
  version: 0.5.3
spec:
  description: "Структурированное логирование плагинов в Loki"
  entryPoint: logger.py
  dependencies:
    - structlog>=21.0.0
    - aiohttp>=3.8.0
  
  config:
    loki_url: "http://loki:3100/loki/api/v1/push"
    plugin_name: "${PLUGIN_NAME}"
    log_level: "info"

И его реализация:

python
# plugins/structured-logger/logger.py
import structlog
import aiohttp
import json
from dsh import plugin

structlog.configure(
    processors=[
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.addLogLevel,
        structlog.processors.JSONRenderer()
    ]
)

logger = structlog.get_logger()

@plugin.handler("log_event")
async def log_to_loki(context):
    """Отправляет структурированные логи в Loki"""
    log_data = {
        "streams": [{
            "stream": {
                "plugin": context.config.plugin_name,
                "level": context.level
            },
            "values": [[
                int(context.timestamp.timestamp() * 1e9),
                json.dumps(context.payload)
            ]]
        }]
    }
    
    async with aiohttp.ClientSession() as session:
        async with session.post(
            context.config.loki_url,
            json=log_data,
            headers={"Content-Type": "application/json"}
        ) as response:
            if response.status != 204:
                await logger.error(f"Loki error: {await response.text()}")
                raise Exception(f"Failed to send log: {response.status}")

async def main():
    await plugin.serve(config_file="config.yaml")

if __name__ == "__main__":
    asyncio.run(main())

Для мониторинга состояния плагинов используем Prometheus Exporter:

yaml
# monitoring/plugin-exporter.yaml
apiVersion: dsh/v1
kind: Plugin
metadata:
  name: prometheus-exporter
  version: 0.8.1
spec:
  description: "Экспорт метрик плагина в Prometheus"
  entryPoint: exporter.py
  dependencies:
    - prometheus_client>=0.16.0
    - psutil>=5.9.0
  
  config:
    listen_port: 8080
    metrics_path: "/metrics"
python
# plugins/prometheus-exporter/exporter.py
from dsh import plugin
from prometheus_client import start_http_server, Counter, Gauge, Histogram
import psutil
import time

# Определяем метрики
tasks_total = Counter('plugin_tasks_total', 'Total tasks processed', ['status', 'plugin'])
tasks_duration = Histogram('plugin_task_duration_seconds', 'Task execution time')
plugin_memory = Gauge('plugin_memory_bytes', 'Plugin memory usage')
plugin_cpu = Gauge('plugin_cpu_percent', 'Plugin CPU usage')

@plugin.handler("task_completed")
@tasks_duration.time()
async def record_task_completion(context):
    """Регистрирует завершение задачи в метриках"""
    tasks_total.labels(
        status=context.payload.get("status", "unknown"),
        plugin=context.config.plugin_name
    ).inc()
    
    plugin_memory.set(psutil.Process().memory_info().rss)
    plugin_cpu.set(psutil.cpu_percent())

async def main():
    # Запускаем HTTP сервер для Prometheus
    start_http_server(context.config.listen_port)
    await plugin.serve(config_file="config.yaml")

if __name__ == "__main__":
    asyncio.run(main())

Настроим Alertmanager для критических событий:

yaml
# monitoring/alertmanager-config.yaml
global:
  resolve_timeout: 5m

route:
  receiver: 'default'
  routes:
    - match:
        severity: critical
      receiver: 'slack-alerts'
      continue: true

receivers:
  - name: 'default'
    webhook_configs:
      - url: 'http://alertmanager:9093/api/v1/alerts'

  - name: 'slack-alerts'
    slack_configs:
      - channel: '#plugin-alerts'
        title: 'Критическая алерма от {{ template "slack.title" . }}'
        text: |
          {{ template "slack.body" . }}

templates:
  - /etc/alertmanager/template.tmpl

И шаблон уведомлений:

yaml
# monitoring/template.tmpl
{{ define "slack.title" }}{{ .CommonAnnotations.summary }}{{ end }}
{{ define "slack.body" }}
*Плагин:* {{ .CommonLabels.plugin }}
*Сервер:* {{ .CommonLabels.instance }}
*Статус:* {{ .CommonLabels.severity }}

{{ range .Alerts }}
*Алерма:* {{ .Annotations.summary }}
{{ if .Annotations.description }}Описание: {{ .Annotations.description }}{{ end }}
{{ end }}
{{ end }}

В результате вы получаете полную картину: логи в Loki, метрики в Prometheus, алерты в Slack — всё это работает автоматически, без ручного сбора данных. Каждый плагин становится частью наблюдаемой системы, что позволяет быстро выявлять и устранять проблемы.

Заключение

DeepSeek Harness не просто предоставляет плагинную архитектуру — он делает её практичной частью вашей операционной модели. С помощью двух примеров:

  1. Автоматизация задач через простое определение плагина и его подключение к очередям сообщений позволяет создавать рабочие лошадки, которые работают без участия человека.
  2. Мониторинг и логирование с использованием стандартных инструментов (Loki, Prometheus, Alertmanager) дает вам полную прозрачность без необходимости писать собственные инструменты сбора данных.

Реализация, которую я описал, проверена на практике — это не теория, а то, что работает в production уже несколько месяцев. Если вам нужно что-то подобное, начните с простого плагина, добавьте логирование, затем подключите метрики — и у вас получится масштабируемая, наблюдаемая система, которая растёт вместе с вашими потребностями.

Поделиться:TelegramX / TwitterVK

Читайте также