Semantic Product Search

Семантический поиск товаров: вместо сопоставления ключевых слов, понимает намерение запроса (embeddings + similarity search) и использует агента для генерации рекомендации по каталогу. Каталог предоставляется в виде MCP-сервера и потребляется отдельным агентом.

🚧 Проект в активной разработке. В настоящее время на Фазе 1 · Настройка бэкенда. Разделы архитектуры, демонстрации и проектных решений будут заполнены позже, когда появится рабочий сквозной поток.

Стек

• API: FastAPI

• Агент / оркестрация: LangChain + LangChain Anthropic (Claude)

• Локальные модели: Ollama

• Наблюдаемость: LangSmith

• Конфигурация / валидация: Pydantic + Pydantic Settings

• База данных: Postgres + pgvector (локальная разработка: SQLite)

• Менеджер пакетов: uv

Related MCP server: Vertex AI Search for Commerce MCP Server

Структура проекта

app/
  main.py           # entrypoint de la API
  api/routes.py      # rutas HTTP
  catalog/           # ingesta + modelos de datos del catálogo
  search/             # embeddings + similarity search
  reviews/
  mcp_server/         # servidor MCP (expone el catálogo/búsqueda como tools)
  agent/               # agente que consume el MCP y arma la recomendación
  core/
    config.py         # settings (variables de entorno)
    db.py              # conexión a Postgres/pgvector
  models/
    schemas.py         # modelos Pydantic compartidos
tests/

Локальная настройка

Требования: Python >= 3.12 и установленный uv.

# Instalar dependencias
uv sync

# Configurar variables de entorno
cp .env.example .env
# completar ANTHROPIC_API_KEY y LANGSMITH_API_KEY en .env

# Correr el entrypoint
uv run python -m app.main

Переменные окружения

⚠️ Никогда не логируйте значения API-ключей и других секретов (ANTHROPIC_API_KEY, LANGSMITH_API_KEY и т.д.). Если необходимо отладить Settings, выводите только имена полей, которые не прошли проверку, а не их значения — так делает app/core/config.py при валидации во время запуска.

План развития

Разработка организована по фазам (см. доску Notion):

1. Настройка бэкенда

2. Каталог + вложения

3. Семантический поиск

4. Отзывы + комментарии

5. MCP-сервер

6. Агент + рекомендация

7. REST API + потоковая передача

8. Оптимизация

9. Фронтенд + публикация

Архитектура и проектные решения

В ожидании — будет задокументировано на Фазе 9 (PROD-32), как только проект получит сквозной поток, чтобы можно было описать диаграмму, демо и решения (кэширование, retrieval + re-ranking и т.д.) в контексте реальной работы.