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 достаточно выполнить три шага:
- Установите Harness и зависимые компоненты
bash# Установка через pip
pip install deepseek-harness
# Установка необходимых плагинов
pip install deepseek-plugin openai-plugin database-plugin
- Создайте базовую конфигурацию
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"]
- Запустите агент
bash# Запуск агента с конфигурацией
python -m deepseek_harness run --config config.yaml
# Проверка состояния плагинов
python -m deepseek_harness status
Если вы хотите протестировать плагин отдельно, используйте режим разработки:
bash# Режим разработки с горячей перезагрузкой
python -m deepseek_harness dev --config config.yaml
Для продакшн-окружения рекомендуется использовать Docker:
dockerfileFROM 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-образ можно собрать и запустить:
bashdocker build -t deepseek-harness .
docker run -v $(pwd)/config.yaml:/app/config.yaml deepseek-harness
Возможности расширения
DeepSeek Harness поддерживает несколько типов плагинов:
- Модельные плагины — для работы с LLM (DeepSeek, OpenAI, Claude)
- Инструментальные плагины — для парсинга, анализа, преобразования данных
- Хранилищные плагины — для работы с базами данных и файловыми системами
- Сетевые плагины — для HTTP-запросов и WebSocket-соединений
Каждый тип плагина имеет свой набор хуков и точек расширения, что позволяет гибко настраивать поведение агента.
Полезные ссылки
- Graphify: Создание знаний из кода в виде графов
- Навыки реальных инженеров: коллекция из .agents
- DeepSeek Harness: Плагинная архитектура для AI-агентов
- Настройка Ponytail для Claude Code
- Использование DESIGN.md для генерации UI
Как работают плагины
Механизм загрузки плагинов
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:
yamlplugins:
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")
Типичные ошибки при разработке плагинов:
- Отсутствие
plugin.json— система не обнаружит модуль - Неправильный
entry— загрузчик не сможет импортировать модуль - Отсутствие
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
Команда для добавления плагина:
bashdsh 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
Установка и активация плагина:
bashdsh 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, что позволяет видеть, когда инструмент выходит из строя.
Если сравнить с реальной жизнью: это как иметь набор инструментов в мастерской — каждый инструмент находится в своем ящике, но доступен одним движением руки.
Полезные материалы
- Graphify: Создание знаний из кода в виде графов — для визуального представления зависимостей плагинов.
- Навыки реальных инженеров: коллекция из .agents — примеры практического использования плагинов.
- DeepSeek Harness: Плагинная архитектура для AI-агентов — базовая статья, где описана общая архитектура.
- Настройка Ponytail для Claude Code — пример интеграции другого типа плагинов.
- Использование DESIGN.md для генерации UI — как документировать плагинные интерфейсы.
Практические примеры и кейсы использования
Практические примеры и кейсы использования
Автоматизация задач через плагины
Представьте, что вам нужно автоматически обрабатывать входящие запросы, извлекать данные из баз данных и отправлять результаты в 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 не просто предоставляет плагинную архитектуру — он делает её практичной частью вашей операционной модели. С помощью двух примеров:
- Автоматизация задач через простое определение плагина и его подключение к очередям сообщений позволяет создавать рабочие лошадки, которые работают без участия человека.
- Мониторинг и логирование с использованием стандартных инструментов (Loki, Prometheus, Alertmanager) дает вам полную прозрачность без необходимости писать собственные инструменты сбора данных.
Реализация, которую я описал, проверена на практике — это не теория, а то, что работает в production уже несколько месяцев. Если вам нужно что-то подобное, начните с простого плагина, добавьте логирование, затем подключите метрики — и у вас получится масштабируемая, наблюдаемая система, которая растёт вместе с вашими потребностями.