Создание приложения для сопоставления резюме с помощью tRPC, NLP и Vertex AI

Недавно я сделал небольшое приложение на TypeScript, которое сравнивает PDF-резюме с вакансиями. Мне нужен был быстрый способ прототипировать API, поэтому я выбрал tRPC для бэкенда.
tRPC — это RPC-фреймворк с ориентацией на TypeScript, который обещает «end-to-end typesafe APIs» (сквозную типизацию API), то есть я могу делиться типами между клиентом и сервером без написания схем OpenAPI или GraphQL SDL.
На практике это означало, что я мог сосредоточиться на написании логики, а не шаблонного кода. В отличие от REST или GraphQL, tRPC не предоставляет универсальную схему — он просто открывает процедуры (по сути функции) на сервере, которые клиент может вызвать, напрямую разделяя типы входа и выхода.

Почему это полезно? В двух словах, я делал внутренний инструмент (MVP) и уже использовал TypeScript с обеих сторон. Модель tRPC без шагов сборки и с типизацией подошла идеально. В официальной документации tRPC даже отмечено: если я изменю вход или выход серверной функции, TypeScript предупредит меня на клиенте ещё до того, как я отправлю запрос. Это сильно помогает ловить баги на ранних стадиях. В отличие от этого, с REST или GraphQL мне пришлось бы вручную синхронизировать или генерировать схемы. С другой стороны, я понимал, что tRPC жёстко связывает мой API и клиентский код (он не является языконезависимым API), поэтому он лучше всего подходит для проектов «TypeScript-first», как этот, а не для публичных кроссплатформенных API.

Определение роутера tRPC и валидация входных данных

С настроенным tRPC я написал простой роутер для основной операции: анализа двух загруженных PDF-файлов (CV и описания вакансии). Используя tRPC с Zod-form-data, я мог легко валидировать загрузку файлов. Вот упрощённая версия кода роутера:

export const matchRouter = router({   analyzePdfs: baseProcedure     .input(zfd.formData({       vacancyPdf: zfd.file().refine(file => file.type === "application/pdf", {         message: "Only PDF files are allowed",       }),       cvPdf: zfd.file().refine(file => file.type === "application/pdf", {         message: "Only PDF files are allowed",       }),     }))     .mutation(async ({ input }) => {       const [cvText, vacancyText] = await Promise.all([         PDFService.extractText(input.cvPdf),         PDFService.extractText(input.vacancyPdf),       ]);       const result = await MatcherService.match(cvText, vacancyText);       return { matchRequestId, ...result };     }), });

Здесь мутация analyzePdfs принимает multipart-форму с двумя PDF-файлами. Вызовы zfd.file().refine(...)гарантируют, что каждый файл — это PDF. После валидации и загрузки файлов (с помощью вспомогательного FileService) я использую PDFService.extractText(...), чтобы извлечь сырой текст из каждого PDF. Затем вызываю MatcherService.match(cvText, vacancyText), который выполняет сам анализ.Так как tRPC знает типы входа/выхода, мой фронтенд получает полностью типизированные результаты без написания дополнительных DTO. Такой быстрый сетап и строгая типизация сэкономили мне массу времени на MVP.

Извлечение навыков с помощью базового NLP

Когда у меня был чистый текст CV и описания вакансии, нужно было извлечь из них значимые ключевые слова или навыки. Я сделал это просто: использовал комбинацию natural (для токенизации), compromise (для выделения частей речи, например существительных) и фильтр стоп-слов. Например, в MatcherService у меня есть такой хелпер:

private static extractSkills(text: string): Set<string> {   const doc = nlp(text);   const nouns = doc.nouns().out("array"); // nouns are often skills or keywords   const capitalizedWords = text.match(/\b[A-Z][a-zA-Z0-9.-]+\b/g) || [];    // also pick up capitalized words (like frameworks or proper nouns)   return new Set([...nouns, ...capitalizedWords].map(w => w.toLowerCase())); }

Проще говоря, этот код приводит текст к нижнему регистру, пропускает его через NLP-библиотеку compromise, чтобы получить существительные, и с помощью регулярки находит все слова с заглавной буквы (часто это названия технологий). Объединение этих результатов и удаление дубликатов даёт мне набор кандидатов-«навыков» из каждого документа. Это базовое извлечение ключевых слов — не сложный ML, а просто эвристика, но она работает быстро и хорошо подходит для подсветки совпадающих навыков. (Напоминает старые парсеры резюме.) Внешняя модель пока не нужна, достаточно библиотек и небольшой regex-логики в общем сервисе.

Интеграция Vertex AI (Gemini 1.5 Flash) для сопоставления

Для основной логики сопоставления я решил обратиться к Google Vertex AI с новой моделью Gemini 1.5 Flash. Это было нужно в основном для получения структурированного результата сравнения (например, оценка и рекомендации), не реализуя сложную NLP-логику самому. В MatcherService, после очистки текста и извлечения навыков, я формирую промпт и делаю fetch к Vertex. Например:

const aiPrompt = ` Analyze the job description and candidate's CV to provide a structured evaluation.  Job Description: ${cleanedJD}  Candidate CV: ${cleanedCV}  Provide a structured analysis in JSON format with fields "score", "strengths", and "suggestions". `;  const response = await fetch(process.env.AI_API_ENDPOINT!, {   method: "POST",   headers: {     Authorization: process.env.AI_API_TOKEN,     "Content-Type": "application/json",   },   body: JSON.stringify({     contents: [       { role: "user", parts: [{ text: aiPrompt }] }     ]   }) });  const data = await response.json(); if (!data?.candidates?.[0]?.content?.parts?.[0]?.text) {   throw new AIServiceError('Invalid AI response format'); } const rawResponse = data.candidates[0].content.parts[0].text; // Then parse rawResponse as JSON for score, strengths, suggestions...

Здесь я использую fetch, чтобы сделать POST на эндпоинт Vertex AI (указан в AI_API_ENDPOINT), передавая в теле запроса промпт пользователя. Промпт говорит модели сравнить описание вакансии и CV и выдать JSON с оценкой совпадения, сильными сторонами и предложениями. Затем я парсю JSON-текст из data.candidates[0].content.parts[0].text.Этот подход оказался очень удобным — Gemini выдавал результат без написания алгоритма ранжирования. Это ощущается как использование модели в роли «чёрного ящика-сравнивателя». Конечно, это значит, что я доверяю ИИ, и иногда результат требовал очистки или валидации. Но в целом интеграция Gemini позволила сосредоточиться на UI и потоках данных, а не на тонкой настройке LLM. (Пришлось, правда, обрабатывать ошибки и лимиты запросов.)

Почему tRPC подошёл (и его ограничения)

Использование tRPC определённо ускорило разработку. Без необходимости писать схемы API я мог поднять endpoint за считанные минуты. Full-stack TypeScript означает, что код роутера, который я написал выше, — это общий код и для клиента (через генератор клиента tRPC), так что у меня есть проверки во время компиляции. На практике, когда я менял валидацию Zod или возвращаемую структуру, мой React UI сразу переставал компилироваться, пока я не поправлю типы. Это ощущение «автодополнения» — именно то, о чём говорит сайт tRPC. И поскольку tRPC практически не требует шаблонного кода (нет контроллеров, генерации), код оставался лаконичным.

С другой стороны, я знаю про ограничения tRPC. Он жёстко связывает мой фронтенд с этой серверной реализацией, поэтому если бы мне понадобился публичный REST или мобильный клиент, пришлось бы переосмысливать архитектуру. Мне также пришлось самому думать про кеширование и лимиты запросов (tRPC не даёт готового решения, как GraphQL). В блоге Directus очень метко сказано: tRPC отлично подходит для внутренних инструментов на TypeScript, но «ограничивает ваши возможности», если нужна широкая совместимость. Для этого проекта — по сути внутреннего демо — эти ограничения были приемлемы. Я даже добавил простой middleware-лимитер, чтобы мои вызовы Vertex AI не превышали квоту.

Уроки

Создание этого проекта с современными API на TypeScript оказалось довольно приятным. Я получил сквозную типизацию (клиент точно знает, что вернётся, например, { score: number }) и не пришлось поддерживать отдельную клиентскую библиотеку. Код ощущается очень «SDK-подобным»: я просто вызываю функции в matchRouter так, словно это локальный код.

На стороне NLP я понял, что даже простые эвристики (существительные + слова с заглавной буквы) могут неплохо справляться с выделением ключевых слов в простых случаях. И наконец, интеграция Vertex AI напомнила, что многое из «магии AI» можно отдать наружным моделям при грамотной постановке промпта.

Но, как всегда, нет серебряной пули. Если бы у меня было больше времени, я бы улучшил обработку ошибок вокруг AI-сервиса и добавил кеширование результатов (так как PDF-to-text и вызовы AI дорогие). И если бы приложение развивалось дальше, я мог бы заменить tRPC на более привычный REST/GraphQL API для публичного интерфейса. Но пока что tRPC дал именно то, что было нужно: быстрый MVP со строгой типизацией и минимумом церемоний.

Полный исходный код доступен здесь: GitHub Repository.

Sources: Я опирался на несколько ресурсов, пока разбирался с этим проектом. На сайте tRPC подчёркивается принцип «move fast, break nothing» и сквозной TypeScript-подход, а в блогах сравнивается, как tRPC выглядит на фоне REST/GraphQL, отмечая его ориентацию на TypeScript и ограничения.

1. tRPC Official Site – Move Fast and Break Nothing. End-to-end typesafe APIs made easy. (Фокус tRPC на full-stack TypeScript и типизацию).

2. Viljami Kuosmanen, Comparing REST, GraphQL & tRPC (dev.to, Oct 2023) – Обсуждается, как tRPC предоставляет RPC-стиль и делится типами вместо универсальной схемы.

3. Bryant Gillespie, REST vs. GraphQL vs. tRPC (Directus blog, Feb 2025) – Описывает сильные стороны tRPC (минимум шаблонного кода, типизация) и его ограничения (только TypeScript, ограниченный охват).