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

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

DeepSeek Harness превращает всё в плагины: от LLM до инструментов, обеспечивая гибкую AI-инфраструктуру через единый интерфейс.

Обзор DeepSeek Harness

Обзор DeepSeek Harness

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

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

yamlКопировать
# Пример конфигурации агента с плагинами
plugins:
  - name: dsh-plugin-llm
    version: ^2.1.0
  - name: dsh-plugin-vector-db
    config:
      host: "true nas.home"
      port: 6379
  - name: dsh-plugin-filesystem
    config:
      path: "/mnt/storage/knowledge"

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

DeepSeek Harness использует архитектуру plug-and-play, где каждый компонент — это самостоятельный плагин. Плагины загружаются динамически, что позволяет агенту расширять свои возможности без перезапуска.

Основные принципы:

1. Стандартизованный интерфейс — каждый плагин реализует однородный набор методов (initialize, execute, cleanup)
2. Версионирование — плагины управляют зависимостями через semantic versioning
3. Безопасность изоляции — каждый плагин работает в собственной sandbox-среде

bashКопировать
# Установка плагина через менеджер плагинов
dsh plugin install dsh-plugin-llm
dsh plugin install dsh-plugin-vector-db

# Проверка установленных плагинов
dsh plugin list

Пример плагина для локального поиска:

pythonКопировать
# dsh-plugin-local-search.py
class LocalSearchPlugin:
    def initialize(self, config):
        self.knowledge_base = config.get('path', '/var/lib/knowledge')
    
    def execute(self, query):
        # Простой пример: поиск в файлах
        import subprocess
        result = subprocess.run(
            ['rg', '-i', query, self.knowledge_base],
            capture_output=True,
            text=True
        )
        return result.stdout
    
    def cleanup(self):
        # Очистка ресурсов
        pass

Основные компоненты

LLM Плагины — подключение к языковым моделям через единый интерфейс. Поддерживаются OpenAI-совместимые API, локальные модели через Ollama и собственные реализации.

yamlКопировать
# Конфигурация LLM плагина
plugin: dsh-plugin-llm
config:
  provider: "openai"
  model: "gpt-4-turbo"
  api_key: "${OPENAI_API_KEY}"
  base_url: "https://api.openai.com/v1"

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

bashКопировать
# Пример инструментального плагина для работы с базой данных
dsh plugin install dsh-plugin-postgres
dsh plugin configure dsh-plugin-postgres \
  --host "postgres.home" \
  --port 5432 \
  --database "knowledge" \
  --user "agent"

Память и кэширование — плагины для хранения состояния агента. Поддерживаются локальные файловые системы, Redis, PostgreSQL и даже облачные хранилища через единый интерфейс.

yamlКопировать
# Конфигурация плагина памяти
plugin: dsh-plugin-memory
config:
  backend: "redis"
  host: "redis.home"
  port: 6379
  ttl: 3600

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

bashКопировать
# Управление плагинами через CLI
dsh plugin update dsh-plugin-llm
dsh plugin disable dsh-plugin-experimental
dsh plugin enable dsh-plugin-vector-db

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

Настройка плагинов

Установка и активация

Для начала нужно понять, что DeepSeek Harness работает на базе Node.js и использует npm как менеджер пакетов. Если у вас уже есть Node.js версии 18+, можете приступать.

bashКопировать
# Установка DeepSeek Harness глобально
npm install -g @deepseek/harness

# Проверка установки
dsh --version

После установки активируйте плагиновый движок:

bashКопировать
# Инициализация конфигурации Harness
dsh init

# Добавление плагина для LLM (например, OpenAI)
dsh plugin add openai

# Активация плагина
dsh plugin enable openai

Если вам нужен плагин для локального LLM, используйте Hugging Face интеграцию:

bashКопировать
# Установка плагина HF LLM
dsh plugin add huggingface-llm

# Редактирование конфигурации плагина
nano ~/.config/dsh/plugins/huggingface-llm.json

В конфигурации укажите модель и параметры:

jsonКопировать
{
  "model": "Qwen/Qwen2.5-7B-Instruct",
  "endpoint": "http://localhost:8080",
  "context_length": 4096,
  "temperature": 0.7
}

Примеры конфигураций

Базовая конфигурация с несколькими плагинами

Создайте файл dsh-config.yaml в корне проекта:

yamlКопировать
plugins:
  - name: openai
    enabled: true
    config:
      api_key: "${OPENAI_API_KEY}"
      model: gpt-4-turbo
  
  - name: huggingface-llm
    enabled: true
    config:
      model: "Qwen/Qwen2.5-7B-Instruct"
      endpoint: "http://localhost:8080"
  
  - name: web-search
    enabled: true
    config:
      engine: "duckduckgo"
      timeout: 5000

agents:
  - name: "content-generator"
    model: "openai"
    tools: ["web-search", "file-writer"]
  
  - name: "code-assistant"
    model: "huggingface-llm"
    tools: ["file-reader", "terminal"]

Конфигурация для локальной разработки

Для работы в изолированной среде используйте следующую конфигурацию:

yamlКопировать
plugins:
  - name: huggingface-llm
    enabled: true
    config:
      model: "mistralai/Mistral-7B-Instruct-v0.2"
      gpu_layers: 35  # Количество слоев для GPU (если используете llama.cpp)
      context_length: 2048
  
  - name: terminal
    enabled: true
    config:
      shell: "/bin/bash"
      timeout: 30000

agents:
  - name: "debug-assistant"
    model: "huggingface-llm"
    tools: ["terminal", "file-reader"]

Конфигурация с использованием кэширования

Для повышения производительности добавьте Redis кэширование:

yamlКопировать
plugins:
  - name: redis-cache
    enabled: true
    config:
      host: "localhost"
      port: 6379
      ttl: 3600
  
  - name: openai
    enabled: true
    config:
      api_key: "${OPENAI_API_KEY}"
      model: gpt-4-turbo
      cache: true  # Использовать Redis для кэширования запросов
  
  - name: huggingface-llm
    enabled: true
    config:
      model: "Qwen/Qwen2.5-7B-Instruct"
      cache: true

Использование плагина для веб-поиска

Для интеграции с поисковыми системами настройте плагин следующим образом:

yamlКопировать
plugins:
  - name: web-search
    enabled: true
    config:
      engine: "serpapi"
      api_key: "${SERPAPI_API_KEY}"
      region: "ru"
      gl: "ru"
      
  - name: content-generator
    enabled: true
    config:
      model: "openai"
      tools: ["web-search"]
      prompt_template: |
        Используй результаты поиска для создания контента на тему:
        {{query}}
        
        Источник: {{sources}}

Пример конфигурации для продакшена

yamlКопировать
plugins:
  - name: openai
    enabled: true
    config:
      api_key: "${OPENAI_API_KEY}"
      model: gpt-4-turbo
      max_tokens: 1000
      temperature: 0.3
  
  - name: redis-cache
    enabled: true
    config:
      host: "${REDIS_HOST}"
      port: 6379
      password: "${REDIS_PASSWORD}"
      ttl: 7200
  
  - name: monitoring
    enabled: true
    config:
      endpoint: "${GRAFANA_ENDPOINT}"
      api_key: "${GRAFANA_API_KEY}"

agents:
  - name: "production-assistant"
    model: "openai"
    tools: ["redis-cache", "monitoring"]
    max_concurrent: 10
    timeout: 30000

Быстрый старт с базовой конфигурацией

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

bashКопировать
# Создайте базовую конфигурацию
cat > dsh-quick.yaml << EOF
plugins:
  - name: huggingface-llm
    enabled: true
    config:
      model: "Qwen/Qwen2.5-7B-Instruct"

agents:
  - name: "quick-test"
    model: "huggingface-llm"
EOF

# Запустите тестового агента
dsh run -c dsh-quick.yaml agent quick-test "Привет, как дела?"

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

• Инженерные навыки с mattpocock/skills
• Использование Ponytail для ленивых ИИ-агентов
• design-system
• claw-code: Музейный экспонат, управляемый ИИ
• Языковая модель, живущая в секторе загрузки

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

Работа с LLM

DeepSeek Harness делает работу с LLM предсказуемой и структурированной — как systemd для Linux. Вместо того чтобы писать кучу кастомного кода, вы просто подключаете провайдер как плагин.

bashКопировать
# Установка плагина для OpenAI-совместимого API
dsh plugin install openai

# Конфигурация в harness.yml
plugins:
  - name: openai
    endpoint: https://api.openai.com/v1
    model: gpt-4-turbo
    max_tokens: 2048
    temperature: 0.7

Подход похож на использование Docker Compose для микросервисов — всё подключается через один файл, а внутри происходит магия. Например, для работы с локальной моделью через Ollama:

yamlКопировать
# harness.yml
plugins:
  - name: ollama
    endpoint: http://localhost:11434
    model: llama3
    options:
      num_ctx: 2048
      num_batch: 512

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

Использование в agentic-потоках

В agentic-потоках Harness обеспечивает централизованный доступ к инструментам и контексту. Представьте это как шину, которая соединяет агентов, инструментами и данными — как Message Bus в сложной системе.

yamlКопировать
# agentic-workflow.yml
workflow:
  - agent: orchestrator
    tools:
      - name: file-reader
        path: /var/log
      - name: vector-store
        endpoint: http://localhost:6333
  
  - agent: analyzer
    plugins:
      - name: openai
      - name: rag
        source: vector-store

Для RAG-агентов Harness автоматически подтягивает нужные чанки и добавляет их в контекст LLM:

pythonКопировать
# Пример агента с использованием Harness
from deepseek_harness import Agent

agent = Agent(
    model="openai",
    tools=["file-reader", "vector-store"],
    rag_config={
        "top_k": 5,
        "score_threshold": 0.7
    }
)

result = agent.query("Какой последний commit изменил auth.py?")

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

В agentic-потоках также важна предсказуемость. Если вам нужно, чтобы агент всегда использовал определённый инструмент, вы просто настраиваете его в конфигурации:

yamlКопировать
# stable-agent.yml
agents:
  - name: security-scanner
    tools:
      - name: vulnerability-db
        retry_policy:
          max_retries: 3
          backoff: exponential

Это как настроить systemd сервис с ограничениями ресурсов — вы точно знаете, что получите, когда запустите систему.

---

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

Практические кейсы

Автоматизация задач

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

Базовый конфигурационный файл для автоматизации:

yamlКопировать
# dsh-config.yaml
plugins:
  - name: file-watcher
    type: watcher
    watch:
      - /mnt/cloud/storage
    events: [created, modified]
    
  - name: telegram-notifier
    type: notifier
    token: ${TELEGRAM_BOT_TOKEN}
    chat_id: ${TELEGRAM_CHAT_ID}
    
  - name: deepseek-processor
    type: ai-processor
    model: deepseek-coder
    prompt: |
      Проанализируй новый файл {filename} и извлеки важную информацию.
      Если файл содержит данные о финансах, отправь сводку в бухгалтерскую систему.
      
workflow:
  - trigger: file-created
    actions:
      - process-with-deepseek
      - notify-telegram

Пример скрипта для автоматизации:

bashКопировать
#!/bin/bash
# automate-tasks.sh

# Инициализируем DeepSeek Harness
export DS_PLUGIN_PATH="/etc/deepseek/plugins"
export DS_CONFIG="/etc/deepseek/dsh-config.yaml"

# Запускаем наблюдатель за файлами
dsh-plugin file-watcher --config /etc/deepseek/dsh-config.yaml &

# Настраиваем cron-задачи для периодической очистки
echo "0 2 * * * /usr/local/bin/cleanup-logs.sh" | crontab -

# Пример задачи очистки
cat > /usr/local/bin/cleanup-logs.sh << 'EOF'
#!/bin/bash
# Очистка логов старше 30 дней
find /var/log -name "*.log" -mtime +30 -exec rm {} \;
dsh-plugin logger --rotate --keep 7
EOF

chmod +x /usr/local/bin/cleanup-logs.sh

Практический кейс: Обработка фотографий

pythonКопировать
# photo-processor.py
from deepseek_harness import DSPlugin

class PhotoProcessorPlugin(DSPlugin):
    def __init__(self):
        super().__init__(name="photo-processor")
        self.supported_formats = ['.jpg', '.png', '.heic']
    
    def process_photo(self, filepath):
        # Автоматическая категоризация фотографий
        analysis = self.ai_call(
            model="deepseek-vision",
            prompt="Определи на фото: человек, животное, пейзаж или предмет",
            image=filepath
        )
        
        # Сохраняем результат в Nextcloud
        if analysis["category"] == "person":
            self.move_to_album(filepath, "Портреты")
        else:
            self.move_to_album(filepath, "Прочее")
            
        # Создаем миниатюру
        self.create_thumbnail(filepath)

# Регистрация плагина
processor = PhotoProcessorPlugin()
processor.register()

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

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

Конфигурация мониторинга:

yamlКопировать
# monitoring-config.yaml
plugins:
  - name: prometheus-exporter
    type: metrics-exporter
    port: 9090
    metrics:
      - deepseek_requests_total
      - deepseek_response_time_seconds
      - deepseek_plugin_errors
      
  - name: alertmanager
    type: alerting
    endpoint: http://localhost:9093
    rules:
      - name: deepseek-high-latency
        condition: "deepseek_response_time_seconds > 5"
        notification: telegram-bot
        
  - name: structured-logger
    type: logging
    format: json
    output: /var/log/deepseek/events.json
    fields:
      - timestamp
      - agent_id
      - model
      - tokens_used
      - response_time

Пример дашборда Grafana:

jsonКопировать
{
  "dashboard": {
    "title": "DeepSeek Harness Monitoring",
    "panels": [
      {
        "title": "Запросы в секунду",
        "type": "graph",
        "targets": [
          {
            "expr": "rate(deepseek_requests_total[5m])",
            "legendFormat": "{{model}}"
          }
        ]
      },
      {
        "title": "Время ответа модели",
        "type": "graph", 
        "targets": [
          {
            "expr": "deepseek_response_time_seconds",
            "legendFormat": "{{agent}}"
          }
        ]
      },
      {
        "title": "Использование токенов",
        "type": "stat",
        "targets": [
          {
            "expr": "deepseek_tokens_used_bytes / 1024 / 1024"
          }
        ]
      }
    ]
  }
}

Скрипт для логирования событий:

bashКопировать
#!/bin/bash
# log-events.sh

# Функция для логирования событий DeepSeek Harness
log_deepseek_event() {
    local event_type=$1
    local agent_id=$2
    local model=$3
    local details=$4
    
    # Структурированный лог в JSON
    cat << EOF | tee -a /var/log/deepseek/events.json
{
  "timestamp": "$(date -u --iso-8601=seconds)",
  "event_type": "$event_type",
  "agent_id": "$agent_id",
  "model": "$model",
  "details": "$details",
  "hostname": "$(hostname)"
}
EOF
    
    # Отправка в Alertmanager при критических ошибках
    if [[ "$event_type" == "error" ]]; then
        curl -X POST http://localhost:9093/api/v1/alerts \
            -H "Content-Type: application/json" \
            -d "{
                \"alerts\": [{
                    \"labels\": {
                        \"severity\": \"critical\",
                        \"service\": \"deepseek\"
                    },
                    \"annotations\": {
                        \"summary\": \"AI Agent Error\",
                        \"description\": \"Agent $agent_id failed with model $model: $details\"
                    }
                }]
            }"
    fi
}

# Пример использования
log_deepseek_event "agent_started" "photo-processor-01" "deepseek-vision" "Автоматическая обработка фотографий запущена"

Настройка мониторинга производительности:

pythonКопировать
# performance-monitor.py
import psutil
import time
from deepseek_harness import DSPlugin

class PerformanceMonitorPlugin(DSPlugin):
    def __init__(self):
        super().__init__(name="performance-monitor")
        self.metrics = {
            'cpu_usage': [],
            'memory_usage': [],
            'gpu_usage': [],
            'response_times': []
        }
    
    def collect_metrics(self):
        # Сбор системных метрик
        self.metrics['cpu_usage'].append(psutil.cpu_percent(interval=1))
        self.metrics['memory_usage'].append(psutil.virtual_memory().percent)
        
        # Мониторинг GPU если доступно
        if hasattr(psutil, 'gpu_usage'):
            self.metrics['gpu_usage'].append(psutil.gpu_usage())
        
        # Запись метрик в Prometheus
        self.export_to_prometheus()
    
    def export_to_prometheus(self):
        # Экспорт метрик в Prometheus
        with open('/tmp/deepseek_metrics.prom', 'w') as f:
            f.write(f"# HELP deepseek_cpu_usage CPU usage percent\n")
            f.write(f"# TYPE deepseek_cpu_usage gauge\n")
            f.write(f"deepseek_cpu_usage {psutil.cpu_percent()} \n")
            
            f.write(f"# HELP deepseek_memory_usage Memory usage percent\n")
            f.write(f"# TYPE deepseek_memory_usage gauge\n")
            f.write(f"deepseek_memory_usage {psutil.virtual_memory().percent} \n")
    
    def setup_alerts(self):
        # Настройка алертов на основе порогов
        if psutil.cpu_percent() > 80:
            self.trigger_alert("high_cpu", f"CPU usage: {psutil.cpu_percent()}%")
        
        if psutil.virtual_memory().percent > 90:
            self.trigger_alert("high_memory", f"Memory usage: {psutil.virtual_memory().percent}%")

# Инициализация плагина
monitor = PerformanceMonitorPlugin()
monitor.register()

Инженерные навыки с mattpocock/skills Использование Ponytail для ленивых ИИ-агентов design-system claw-code: Музейный экспонат, управляемый ИИ Языковая модель, живущая в секторе загрузки

Часто задаваемые вопросы

Как DeepSeek Harness упрощает интеграцию новых инструментов в AI-агентов?

В DeepSeek Harness каждый инструмент оформляется как плагин с единым интерфейсом (initialize, execute, cleanup). Вы пишете плагин один раз, добавляете его в конфигурацию YAML, и он автоматически появляется в списке доступных возможностей агента. Такой подход устраняет необходимость переписывать код агента при подключении нового инструмента, что особенно ценно в домашней лаборатории, где часто меняются источники данных.

Какие преимущества sandbox-изоляции плагинов в DeepSeek Harness?

Каждый плагин работает в изолированной sandbox-среде, что предотвращает утечку данных и нестабильность одного плагина, влияющую на весь агент. Изоляция также позволяет безопасно экспериментировать с новыми версиями плагинов без риска для продакшн-инфраструктуры. Благодаря этому вы можете быстро тестировать и развертывать плагины, зная, что они не нарушат работу других компонентов.

Как управлять версиями плагинов в DeepSeek Harness?

DeepSeek Harness использует semantic versioning для плагинов, что позволяет явно указывать требуемую версию в конфигурации (например, version: ^2.1.0). Команда dsh plugin install автоматически разрешает совместимые версии, а dsh plugin list показывает текущие установки. Такой подход гарантирует предсказуемость конфигураций и защищает вас от неожиданных обновлений, которые могут сломать работу агента.

Можно ли использовать DeepSeek Harness в домашней лаборатории с локальным хранилищем данных?

Да, DeepSeek Harness идеально подходит для домашней лаборатории: плагин vector-db подключается к локальному Redis или другим базам данных, а плагин filesystem предоставляет доступ к локальному Knowledge-разделу. После однократной настройки плагинов все последующие агенты автоматически получают доступ к этим ресурсам без дополнительной настройки. Это позволяет централизовать управление данными и инструментами, сохраняя при этом гибкость для экспериментов.