Гибридный AI-агент на Ollama и Transformers с LangChain

kirilljsx

Обложка: Как построить гибридный AI-агент на Ollama и Hugging Face Transformers с LangChain для локального code generation в микросервисах: гайд 2026

Хайп хайпом, но на проде код всё равно нужно генерировать где-то локально. Если ты развиваешь микросервисный стек и хочешь встроить code generation без зависимостей от облачных API, то комбинация Ollama + Hugging Face Transformers + LangChain — это не маркетинговое решение, а реально работающий инструмент. Давайте разберёмся, как это собрать и чтобы оно не жрало все ресурсы.

Практически, речь идёт о локальном LLM-агенте, который крутится прямо у тебя на железе, может дёргать инструменты (парсер кода, шаблоны, нейросеть), и генерировать код для микросервисов без утечек данных. Это важно, если ты работаешь с легаси-архитектурой или нужна полная автономность окружения.

Архитектура: как это вообще работает

Оллама — это по сути обёртка над llama.cpp, которая поднимает GGUF-модели прямо на твоей машине. Hugging Face Transformers — это мощная библиотека для работы с LLM на Python, когда нужна гибкость. LangChain связывает всё это вместе: управляет контекстом, цепочками промптов, подключает память и внешние инструменты.

Вот что происходит под капотом: ты даёшь LangChain задачу (“сгенерируй API обработчик”), он разбирает, что нужно, может обратиться к Ollama (если модель уже поднята) или использовать локальный Transformers пайплайн, всё это обрабатывает и возвращает результат. Никаких облачных запросов, никаких задержек на сеть.

По опыту внедрения можно сказать: выбор между Ollama и Transformers зависит от того, как ты собираешься развертывать. Ollama хороша, если ты просто хочешь запустить готовую модель и работать через она-вот-она-тут API. Transformers подходит лучше, если нужна гибкость в кастомизации, fine-tuning или встраивание в сложный пайплайн.

Параметр	Ollama	Transformers	Когда что выбрать
Развертывание	Минимальная настройка, готовая модель	Требует Python окружения и зависимостей	Ollama - если быстрое начало, Transformers - если гибкость
Кастомизация	Через Modelfile, ограничена	Через код, полная свобода	Transformers если нужны особые pre/post-processing
Scalability	Привязана к локальному железу	Можно использовать облако (HuggingFace Endpoints)	Transformers если планируешь масштабирование
Модели	Только GGUF кванты	Все форматы (fp32, fp16, int8 и т.д.)	Ollama если модель уже квантована в GGUF
Speed	Быстро, всё готово	Чуть дольше инициализация, но оптимальнее	Ollama для live-демо, Transformers для батчей

Локальная жизнь: поднимаем стек

Первое — Ollama. Установка банальна: скачиваешь с оффициального сайта, запускаешь, и у тебя крутится лёгкий HTTP-сервис на localhost:11434. Модели хранятся в ~/.ollama/models. Когда ты пишешь ollama run llama2, она скачивается из Hub и тут же заходит.

Второе — Transformers и LangChain. В requirements.txt кидаешь:

transformers
langchain
langchain-community
langchain-huggingface
requests
python-dotenv

Это минимум, чтобы работало. Pip install, и движемся дальше.

Третье — понимаешь, где какая модель будет жить. Если ты юзаешь Ollama, то она там же, в Ollama. Если Transformers — она кешируется в ~/.cache/huggingface/hub/. На проде оба варианта жрут память, поэтому выбирай исходя из того, сколько VRAM у тебя есть. По опыту внедрения: для code generation обычно хватает 3-7 GB, если брать GGUF кванты (IQ3_M, Q4_K_M). Fp32 модели требуют намного больше.

Список действий для setup:

Установи Ollama и запусти демон (ollama serve или в фоне).
Установи Python зависимости через pip.
Создай конфиг, где указываешь, какую модель и где искать (переменные окружения удобнее всего).
Напиши простой скрипт, который проверяет, что Ollama доступна и модель загруженная.
Подключи LangChain с цепочкой промптов для твоего use case.

Code generation агент: как его собрать

Агент в LangChain — это условно цепочка логики: ты даёшь ему несколько инструментов (tools), и она сама решает, какой использовать для решения задачи. Для code generation это может быть парсер синтаксиса, шаблон микросервиса, проверка на типы, всё что угодно.

Вот примерная архитектура агента:

from langchain.agents import initialize_agent, AgentType
from langchain_community.llms import Ollama
from langchain.tools import tool

llm = Ollama(model="llama2", base_url="http://localhost:11434")

@tool
def validate_code(code: str) -> str:
    """Проверяет синтаксис Python кода"""
    try:
        compile(code, '<string>', 'exec')
        return "Синтаксис валиден"
    except SyntaxError as e:
        return f"Ошибка: {e}"

@tool
def apply_template(service_type: str) -> str:
    """Возвращает шаблон микросервиса"""
    templates = {
        "api": "from fastapi import FastAPI\napp = FastAPI()\n",
        "worker": "import celery\napp = celery.Celery()\n"
    }
    return templates.get(service_type, "Неизвестный тип")

tools = [validate_code, apply_template]

agent = initialize_agent(
    tools,
    llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

result = agent.run(
    "Сгенерируй FastAPI endpoint для обработки JSON"
)
print(result)

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

Ключевые моменты:

RAG-интеграция: если ты хочешь, чтобы агент знал о твоём легаси-коде, встраивай примеры в контекст через Retrieval-Augmented Generation. LangChain поддерживает это из коробки.
Промптирование: вложи усилие в system prompt. Чем точнее ты опишешь, что нужно делать, тем меньше галлюцинаций. По опыту внедрения: “Ты генератор FastAPI кода. Используй только библиотеки X, Y, Z. Всегда добавляй type hints.” работает намного лучше, чем просто “сгенерируй код”.
Кванты модели: для code generation лучше всего работают Q5_K_M или Q4_K_M кванты. Они держат баланс между качеством и потреблением памяти.

Hugging Face Transformers вместо Ollama: когда это имеет смысл

Если Ollama жрёт слишком много памяти или тебе нужна более гибкая кастомизация, можешь использовать Transformers напрямую. Это даёт тебе полный контроль над моделью — какие слои оставить, какие параметры настроить.

Вот как это выглядит:

from transformers import AutoTokenizer, AutoModelForCausalLM
from langchain_community.llms.huggingface_pipeline import HuggingFacePipeline

model_name = "meta-llama/Llama-2-7b-hf"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype="auto",
    device_map="auto"
)

from transformers import pipeline
pipe = pipeline(
    "text-generation",
    model=model,
    tokenizer=tokenizer,
    max_length=512
)

llm = HuggingFacePipeline(pipeline=pipe)

Преимущества такого подхода:

Ты можешь загрузить модель в half-precision (fp16) или int8, чтобы уменьшить footprint.
Полный контроль над генерацией: temperature, top_p, repetition_penalty.
Возможность использовать quantization библиотеки типа bitsandbytes для экстремального сжатия.
Легче встраивается в батч-процессы и Kubernetes поды.

Минус — нужно самому управлять CUDA/CPU, потреблением памяти, всеми этими радостями. На проде это часто оборачивается балансировкой между потреблением и задержками.

Выбор в пользу Transformers если:

Твоя модель занимает 10+ GB и нужна оптимизация.
Ты хочешь встроить fine-tuned модель, обученную на твоём коде.
Нужна интеграция с пайплайнами обработки данных (например, embedding’и для RAG).
Планируешь развертывание в Kubernetes и нужен контроль над инициализацией.

Микросервисная архитектура: как прикрутить агента

Микросервисы обычно требуют изоляции. Один AI-агент не может быть монолитом для всего стека. Вместо этого его стоит разбить на несколько сервисов.

Вот примерная топология:

Model Server — сервис с Ollama или Transformers, отдаёт генерацию через API.
Agent Orchestrator — LangChain логика, дёргает Model Server, применяет tools, управляет flow.
Code Validator — отдельный микросервис для проверки сгенерированного кода (линтеры, type checkers).
Cache Layer — Redis или что-то похожее, чтобы не перегенерировать одно и то же.
Worker Pool — для батч-генерации, если нужно.

Диаграмма взаимодействия:

Client Request
    |
    v
[Agent Orchestrator] -> [Model Server (Ollama/Transformers)]
    |                          |
    +-> [Code Validator]       +-> [GPU/CPU Memory]
    |
    +-> [Cache Layer (Redis)]
    |
    +-> [Tools] (templates, parsers)
    |
    v
Response with Generated Code

Практическая реализация:

Agent Orchestrator — FastAPI приложение, которое слушает запросы и координирует.
Model Server — отдельный контейнер (или даже отдельная машина), только Ollama и всё.
Кеширование — промпт + параметры хешируются, и если видел такой запрос, отдаёшь кеш.
Мониторинг — обязательна метрика “сколько токенов сгенерировалось”, “сколько времени генерация занимает”, “сколько памяти жрёт модель”.

В Docker композ это может выглядеть так:

services:
  ollama:
    image: ollama/ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    environment:
      - OLLAMA_NUM_GPU=1

  agent:
    build: ./agent
    ports:
      - "8000:8000"
    depends_on:
      - ollama
      - redis
    environment:
      - OLLAMA_HOST=http://ollama:11434
      - REDIS_URL=redis://redis:6379

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  ollama_data:

Интеграция с LangChain: управление контекстом и памятью

LangChain — это фреймворк для построения цепочек LLM запросов. В контексте нашего агента это критично, потому что code generation требует понимания контекста: “где генерируем код, какие есть зависимости, какие есть примеры”.

Вот как можно построить цепочку:

from langchain.prompts import PromptTemplate
from langchain.chains import LLMChain
from langchain.memory import ConversationBufferMemory

memory = ConversationBufferMemory(memory_key="chat_history")

prompt = PromptTemplate(
    input_variables=["service_type", "requirements", "chat_history"],
    template="""Ты генератор микросервисного кода на Python.
Тип сервиса: {service_type}
Требования: {requirements}
История:
{chat_history}

Сгенерируй готовый к запуску код."""
)

chain = LLMChain(
    llm=llm,
    prompt=prompt,
    memory=memory
)

response = chain.run(
    service_type="FastAPI API",
    requirements="обработка JSON с валидацией"
)

Мемория здесь нужна для того, чтобы агент помнил предыдущие ошибки и запросы. По опыту внедрения: ConversationBufferMemory быстро переполняется (контекст модели ограничен), поэтому лучше использовать ConversationSummaryMemory с automatic summarization.

Важные моменты при работе с памятью и контекстом:

Token limit: Llama 2 имеет контекст 4096 токенов, Llama 3 — 8192. Если история + промпт + генерируемый код превышают лимит, модель начнёт галлюцинировать.
Compression: используй инструменты для сжатия истории (summarization) каждые N запросов.
RAG для примеров: вместо того, чтобы суёшь всю историю в контекст, кешируй примеры в Vector Store и pull’й релевантные примеры через semantic search.

Оптимизация: бенчмарки и реальность

Хайп хайпом, но давайте смотреть бенчмарки. На железе типа NVIDIA T4 (16 GB VRAM) с GGUF кванты (Q4_K_M) Llama 2 7B генерирует code со speed примерно 15-25 токенов в секунду. Это не быстро для фронтенда (пользователь ждёт), но приемлемо для батч-процессов и девтулз.

Мемория:

Ollama с Llama 2 7B (Q4_K_M): 4-5 GB RAM + 2 GB для буферов.
Transformers с тем же (fp16): 7-10 GB RAM.
Без оптимизации (fp32): 15+ GB RAM.

Время инициализации:

Ollama: если модель уже loaded, первый запрос 100-200ms. Если холодный старт, +1-2 секунды.
Transformers: зависит от того, есть ли кеш. С кешем 50-150ms, без кеша может быть 5-10 секунд.

Метрики для мониторинга на проде:

Latency: P50, P95, P99 latency генерации. Следи за тем, не растёт ли.
Throughput: сколько запросов в секунду обрабатывается. Это зависит от batch size и GPU memory.
Error rate: сколько сгенерированного кода падает при валидации. Если растёт — нужно переучивать промпт или модель.
VRAM usage: следи за утечками. LLM любят их.
Token efficiency: сколько input токенов vs output токенов. Если ratio плохой, значит ты много передаёшь, мало генерируешь.

Таблица реальных чисел (empirically):

Модель	Квант	VRAM	Latency (P50)	Tokens/sec
Llama 2 7B	Q4	5GB	200ms	20
Llama 2 13B	Q4	9GB	350ms	18
Llama 3 8B	Q5	7GB	250ms	22
Mistral 7B	Q4	4.5GB	180ms	25

Если нужна — выбирай Mistral. Если качество кода — Llama 3. По опыту внедрения: для production code generation лучше всего работает Llama 3 в Q5_K_M, хотя это медленнее, зато меньше ошибок.

Deployment в проде: контейнеры, K8s, мониторинг

Локальный стек — это хорошо для разработки. Но в проде нужна надёжность. Вот практические советы:

Docker:

FROM nvidia/cuda:12.2.0-runtime-ubuntu22.04

WORKDIR /app

RUN apt-get update && apt-get install -y python3-pip

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Kubernetes:

apiVersion: v1
kind: Pod
metadata:
  name: agent-pod
spec:
  containers:
  - name: agent
    image: agent:latest
    resources:
      requests:
        memory: "8Gi"
        nvidia.com/gpu: "1"
      limits:
        memory: "10Gi"
        nvidia.com/gpu: "1"
    env:
    - name: OLLAMA_HOST
      value: "http://ollama-service:11434"
  - name: ollama
    image: ollama/ollama
    resources:
      requests:
        memory: "6Gi"
        nvidia.com/gpu: "1"
      limits:
        memory: "8Gi"
        nvidia.com/gpu: "1"

Критичные моменты:

Resource limits: если не установишь, контейнер может убить весь нод.
Health checks: убедись, что модель инициализирована, перед тем как отдавать трафик.
Model persistence: кеши моделей должны быть на отдельном volume, не в контейнере (иначе каждый раз перезагружаются).
Graceful shutdown: когда pod падает, нужно закончить текущий запрос, а не рубить посередине.

Мониторинг:

from prometheus_client import Counter, Histogram, Gauge

generation_latency = Histogram('generation_latency_seconds', 'Latency of generation')
generation_counter = Counter('generations_total', 'Total generations')
memory_usage = Gauge('memory_usage_bytes', 'Memory usage')

@app.post("/generate")
async def generate(request: GenerateRequest):
    with generation_latency.time():
        try:
            result = agent.run(request.prompt)
            generation_counter.inc()
            return {"code": result}
        except Exception as e:
            generation_counter.labels(status="error").inc()
            raise

Осознание, что работаешь с LLM на проде, требует другой ментальности. По опыту внедрения: чем меньше ты доверяешь модели, тем лучше. Всегда валидируй output, всегда имей fallback, всегда логируй. Галлюцинации — это не баг, это фича LLM, и её нужно предусматривать.

Дальше: что вообще пропустили

Мы разобрали базовую архитектуру, но реальность сложнее. Если ты серьёзно внедряешь code generation в микросервисы, нужно подумать о том, как структурировать промпты для разных типов кода (API, Workers, DAOs). Как организовать fine-tuning, если стандартные модели генерируют код, который не подходит под твою архитектуру. Как интегрировать это с IDE-плагинами или CI/CD пайплайнами.

Также — это всё находится в зоне быстрого развития. Модели улучшаются (Llama 3, Code Llama, Mistral), инструменты становятся лучше. По опыту внедрения: лучше выбрать гибкую архитектуру сейчас (Transformers, а не только Ollama), чтобы потом легко переходить на более новые модели без переписывания интеграции.