Поиск через Serper: web_search — выдача Google, search_images — Google Картинки

- web_search: верх выдачи Google через Serper (ответ, 6 результатов со сниппетами, новости) — ~$0.001 за запрос
  вместо серверного поиска OpenRouter ($0.014) и отдельного агента-поисковика
- search_images: Google Картинки (фото людей, мемы) — прямые ссылки, миниатюры как запасные, подпись, сайт, размер
- attach_media принимает до 20 ссылок: оригиналы и запасные миниатюры
- Оба инструмента включает SERPER_API_KEY; WEB_SEARCH, Wikimedia Commons и prompts/web-search.md убраны

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
yunogasai
2026-10-13 23:39:48 +02:00
parent cce3fca94b
commit 1a7271a491
14 changed files with 164 additions and 216 deletions

View File

@@ -49,12 +49,10 @@ interface ModelChoice {
model: string;
/** Отправлять ли модели фото из вопроса и из сообщения, на которое ответили. */
imageInput: boolean;
/** Поиск в интернете — серверный инструмент OpenRouter, поэтому только для моделей через OpenRouter. */
webSearch: boolean;
}
/** Есть ключ OpenRouter — Gemini 3.8 Flash (видит фото), иначе DeepSeek напрямую (только текст). */
const defaultModel = (): Omit<ModelChoice, "webSearch"> =>
const defaultModel = (): ModelChoice =>
envValue("OPENROUTER_API_KEY")
? { model: "openrouter/google/gemini-3.8-flash", imageInput: true }
: { model: "deepseek/deepseek-flash", imageInput: false };
@@ -69,16 +67,6 @@ const parseBool = (name: string): boolean | undefined => {
throw new Error(`${name} должно быть true или false, получено "${raw}"`);
};
/** Поиск по умолчанию включён для моделей OpenRouter; WEB_SEARCH=false — выключить (поиск платный). */
const parseWebSearch = (provider: string): boolean => {
const enabled = parseBool("WEB_SEARCH");
const isOpenRouter = provider === "openrouter";
if (enabled && !isOpenRouter) throw new Error("WEB_SEARCH работает только с моделями OpenRouter");
return isOpenRouter && enabled !== false;
};
/** Модель из AI_MODEL (фото — только если AI_IMAGE_INPUT=true) или по умолчанию + проверка ключа провайдера. */
const parseModel = (): ModelChoice => {
const customModel = envValue("AI_MODEL");
@@ -97,7 +85,7 @@ const parseModel = (): ModelChoice => {
if (keyName) required(keyName);
return { model, imageInput, webSearch: parseWebSearch(provider) };
return { model, imageInput };
};
/** Путь к SQLite; нужен боту и скриптам (`seed`, импорт), которым остальные переменные не нужны. */
@@ -115,6 +103,8 @@ export const loadBotConfig = () => ({
ai: parseModel(),
/** Бюджет токенов на весь промпт; сверх него Mastra Memory срезает самые старые реплики диалога. */
contextTokenLimit: positiveInt("CONTEXT_TOKEN_LIMIT", 12_000),
/** Ключ Serper.dev — поиск в Google и Google Картинках; без него агент не ищет в интернете. */
serperApiKey: envValue("SERPER_API_KEY"),
/** Потолок длины ответа в токенах — длиннее Telegram всё равно режет на несколько сообщений. */
answerTokenLimit: positiveInt("ANSWER_TOKEN_LIMIT", 1_500),
});

View File

@@ -2,6 +2,7 @@ import { BOT_COMMANDS } from "./bot/commands.js";
import { createBot } from "./bot/create-bot.js";
import { DB_PATH, HISTORY_LIMIT, MEMORY_DB_PATH, loadBotConfig } from "./config.js";
import { createDb } from "./libs/db.js";
import { createSerperClient } from "./libs/serper.js";
import { createChatMemberRepository } from "./repositories/chat-member-repository.js";
import { createChatSettingsRepository } from "./repositories/chat-settings-repository.js";
import { createMessageRepository } from "./repositories/message-repository.js";
@@ -42,7 +43,7 @@ const assistantService = createAssistantService({
model: config.ai.model,
memory: createAssistantMemory({ path: MEMORY_DB_PATH, maxTokens: config.contextTokenLimit }),
imageInput: config.ai.imageInput,
webSearch: config.ai.webSearch,
serper: config.serperApiKey ? createSerperClient(config.serperApiKey) : undefined,
answerTokenLimit: config.answerTokenLimit,
chatHistoryService,
chatMemberService,
@@ -74,6 +75,6 @@ await bot.start({
onStart: (me) =>
console.log(
`Бот @${me.username} запущен, модель ${config.ai.model}, ` +
`фото: ${config.ai.imageInput ? "да" : "нет"}, поиск: ${config.ai.webSearch ? "да" : "нет"}`,
`фото: ${config.ai.imageInput ? "да" : "нет"}, поиск: ${config.serperApiKey ? "да" : "нет"}`,
),
});

View File

@@ -41,7 +41,7 @@ const clean = (value: string): string => decodeEntities(value).replace(/\s+/g, "
export const imageAlt = (html: string): string => truncate(clean(html.replace(/<[^>]*>/g, " ")), MAX_ALT_LENGTH);
/** Без повторов по ссылке; из повторов остаётся первый. */
export const uniqueByUrl = <T extends { url: string }>(items: T[]): T[] =>
const uniqueByUrl = <T extends { url: string }>(items: T[]): T[] =>
items.filter((item, index) => items.findIndex((other) => other.url === item.url) === index);
/** Атрибуты тега: имена в нижнем регистре, значения без кавычек и HTML-сущностей. */

56
src/libs/serper.ts Normal file
View File

@@ -0,0 +1,56 @@
import { truncate } from "./telegram-format.js";
const API_URL = "https://google.serper.dev";
const TIMEOUT_MS = 10_000;
/** Бот русскоязычный: выдача Google для России на русском. */
const LOCALE = { gl: "ru", hl: "ru" };
/** 10 результатов — один кредит Serper; больше модели и не нужно. */
const RESULTS = 10;
export interface SerperSearch {
answerBox?: { title?: string; answer?: string; snippet?: string };
knowledgeGraph?: { title?: string; type?: string; description?: string };
organic?: { title: string; link: string; snippet?: string; date?: string }[];
topStories?: { title: string; link: string; source?: string; date?: string }[];
}
export interface SerperImages {
images?: {
title: string;
imageUrl: string;
imageWidth?: number;
imageHeight?: number;
thumbnailUrl?: string;
domain?: string;
link?: string;
}[];
}
/**
* Serper.dev — выдача Google через API: обычный поиск и Google Картинки. Ключ — SERPER_API_KEY,
* запрос — один кредит (2500 бесплатно, дальше ~$1 за 1000).
*/
export const createSerperClient = (apiKey: string) => {
const request = async <T>(endpoint: string, query: string): Promise<T> => {
const response = await fetch(`${API_URL}/${endpoint}`, {
method: "POST",
headers: { "x-api-key": apiKey, "content-type": "application/json" },
body: JSON.stringify({ q: query, num: RESULTS, ...LOCALE }),
signal: AbortSignal.timeout(TIMEOUT_MS),
});
if (!response.ok) throw new Error(`Serper ответил ${response.status}: ${truncate(await response.text(), 200)}`);
return (await response.json()) as T;
};
return {
search: (query: string) => request<SerperSearch>("search", query),
images: (query: string) => request<SerperImages>("images", query),
};
};
export type SerperClient = ReturnType<typeof createSerperClient>;

View File

@@ -1,74 +0,0 @@
import { imageAlt, type PageImage } from "./html-images.js";
const API_URL = "https://commons.wikimedia.org/w/api.php";
/** Wikimedia просит представляться своим User-Agent — иначе API может отказать. */
const USER_AGENT = "BoltunBot/1.0 (Telegram bot)";
const TIMEOUT_MS = 10_000;
/** Ширина превью: оригиналы бывают по 20 МБ, а Telegram всё равно сжимает фото до ~1280 px. */
const THUMB_WIDTH = 1280;
/** Без превью годится только оригинал, который Telegram покажет сам. */
const SHOWN_MIME_TYPES = ["image/jpeg", "image/png", "image/webp", "image/gif"];
interface CommonsPage {
index: number;
title: string;
imageinfo?: {
mime: string;
url: string;
thumburl?: string;
extmetadata?: Record<string, { value: string } | undefined>;
}[];
}
const toImage = (page: CommonsPage): PageImage[] => {
const info = page.imageinfo?.[0];
if (!info?.mime.startsWith("image/")) return [];
const url = info.thumburl ?? (SHOWN_MIME_TYPES.includes(info.mime) ? info.url : undefined);
if (!url) return [];
const meta = info.extmetadata;
return [{ url, alt: imageAlt(meta?.ImageDescription?.value ?? meta?.ObjectName?.value ?? page.title.replace(/^File:/, "")) }];
};
/**
* Поиск фотографий в Wikimedia Commons — бесплатно и без ключа, ссылки сразу на файлы.
* Ищет по словам в названии и описании, поэтому лучше коротко и по-английски: «capybara», «Eiffel Tower night».
*/
export const searchCommonsImages = async (query: string, limit: number): Promise<PageImage[]> => {
const params = new URLSearchParams({
action: "query",
format: "json",
formatversion: "2",
generator: "search",
gsrsearch: query,
gsrnamespace: "6",
// Часть файлов — PDF и видео, их отбрасываем: берём с запасом.
gsrlimit: String(limit * 2),
prop: "imageinfo",
iiprop: "url|mime|extmetadata",
iiextmetadatafilter: "ImageDescription|ObjectName",
iiurlwidth: String(THUMB_WIDTH),
});
const response = await fetch(`${API_URL}?${params}`, {
headers: { "user-agent": USER_AGENT },
signal: AbortSignal.timeout(TIMEOUT_MS),
});
if (!response.ok) throw new Error(`Wikimedia Commons ответил ${response.status}`);
const { query: result } = (await response.json()) as { query?: { pages?: CommonsPage[] } };
return (result?.pages ?? [])
.sort((a, b) => a.index - b.index)
.flatMap(toImage)
.slice(0, limit);
};

View File

@@ -3,6 +3,7 @@ import { ProviderHistoryCompat, ToolCallFilter } from "@mastra/core/processors";
import { RequestContext } from "@mastra/core/request-context";
import type { Memory } from "@mastra/memory";
import { readPrompt } from "../../libs/prompts.js";
import type { SerperClient } from "../../libs/serper.js";
import type { Persona, ReplyAttachment } from "../../types.js";
import type { ChatHistoryService } from "../chat-history-service.js";
import type { ChatMemberService } from "../chat-member-service.js";
@@ -18,6 +19,7 @@ import { createPageImagesTool } from "./tools/page-images-tool.js";
import { createReadChatMessagesTool } from "./tools/read-chat-messages-tool.js";
import { createReadMemberMessagesTool } from "./tools/read-member-messages-tool.js";
import { assistantRequestContextSchema, type AssistantRequestContext } from "./tools/request-context.js";
import { createSearchImagesTool } from "./tools/search-images-tool.js";
import { createWebSearchTool } from "./tools/web-search-tool.js";
export type { Question } from "./prompts.js";
@@ -36,14 +38,14 @@ interface AssistantServiceDeps {
answerTokenLimit: number;
/** Умеет ли модель смотреть изображения; если нет — фото ей не отправляем. */
imageInput: boolean;
/** Давать ли агенту поиск в интернете (серверный поиск OpenRouter). */
webSearch: boolean;
/** Поиск в Google и Google Картинках; нет ключа Serper — агент без поиска. */
serper?: SerperClient;
chatHistoryService: ChatHistoryService;
chatMemberService: ChatMemberService;
}
/**
* Шаги агента: до четырёх шагов с инструментами (например, архив → поиск с картинками → прикрепить, и один в запас)
* Шаги агента: до четырёх шагов с инструментами (например, архив → поиск картинок → прикрепить, и один в запас)
* и последний — всегда текстовый ответ (см. final-response.ts). Каждый шаг заново отправляет всё прочитанное
* в этом ответе, поэтому шагов немного.
*/
@@ -68,7 +70,7 @@ export const createAssistantService = ({
memory,
answerTokenLimit,
imageInput,
webSearch,
serper,
chatHistoryService,
chatMemberService,
}: AssistantServiceDeps) => {
@@ -103,7 +105,7 @@ export const createAssistantService = ({
createReadChatMessagesTool(chatHistoryService),
createListChatMembersTool(chatMemberService),
createReadMemberMessagesTool({ chatHistoryService, chatMemberService }),
...(webSearch ? [createWebSearchTool({ model })] : []),
...(serper ? [createWebSearchTool(serper), createSearchImagesTool(serper)] : []),
createPageImagesTool(),
createAttachMediaTool(),
createAttachFileTool(),

View File

@@ -3,6 +3,9 @@ import { z } from "zod";
import { describeAttachment, downloadFirst, MAX_ATTACHMENTS } from "../attachments.js";
import { assistantRequestContextSchema } from "./request-context.js";
/** Ссылок можно дать больше, чем вложений: остальные — запасные (например, миниатюры из search_images). */
const MAX_URLS = 2 * MAX_ATTACHMENTS;
export const createAttachMediaTool = () =>
createTool({
id: "attach_media",
@@ -15,8 +18,8 @@ export const createAttachMediaTool = () =>
urls: z
.array(z.string().min(1))
.min(1)
.max(MAX_ATTACHMENTS)
.describe("Прямые ссылки на файлы, лучшие первыми: из web_search (images), page_images или от пользователя."),
.max(MAX_URLS)
.describe("Прямые ссылки на файлы, лучшие первыми: из search_images, page_images или от пользователя."),
count: z
.number()
.int()

View File

@@ -0,0 +1,40 @@
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
import { errorMessage } from "../../../libs/error-message.js";
import { imageAlt } from "../../../libs/html-images.js";
import type { SerperClient } from "../../../libs/serper.js";
/** Список уходит модели и повторяется в каждом её следующем шаге — с запасом на битые ссылки, но не больше. */
const MAX_IMAGES = 8;
export const createSearchImagesTool = (serper: SerperClient) =>
createTool({
id: "search_images",
description:
"Ищет картинки в Google Картинках: фото людей, мемы, места, вещи — что угодно. Возвращает прямые ссылки на картинки " +
"(url), запасные миниатюры (thumbnail), подписи и сайты. Чтобы прикрепить — передай в attach_media url подходящих " +
"картинок, лучшие первыми, а в конец списка — их thumbnail на случай, если оригиналы не скачаются.",
inputSchema: z.object({
query: z.string().min(1).describe("Запрос как в Google Картинках: «Илон Маск», «капибара мем», «Эйфелева башня ночью»."),
}),
execute: async ({ query }) => {
try {
const images = ((await serper.images(query)).images ?? []).slice(0, MAX_IMAGES);
if (images.length === 0) return { status: "empty", result: "Картинок не нашлось — попробуй другой запрос." };
return {
status: "ok",
images: images.map(({ title, imageUrl, imageWidth, imageHeight, thumbnailUrl, domain }) => ({
url: imageUrl,
thumbnail: thumbnailUrl,
title: imageAlt(title),
source: domain,
...(imageWidth && imageHeight && { size: `${imageWidth}x${imageHeight}` }),
})),
};
} catch (error) {
return { status: "error", result: `Поиск картинок не сработал: ${errorMessage(error)}.` };
}
},
});

View File

@@ -1,120 +1,57 @@
import { Agent } from "@mastra/core/agent";
import { createTool } from "@mastra/core/tools";
import { z } from "zod";
import { errorMessage } from "../../../libs/error-message.js";
import { uniqueByUrl, type PageImage } from "../../../libs/html-images.js";
import { fetchPageImages } from "../../../libs/page-images.js";
import { readPrompt } from "../../../libs/prompts.js";
import { searchCommonsImages } from "../../../libs/wikimedia-commons.js";
import type { SerperClient, SerperSearch } from "../../../libs/serper.js";
/**
* Серверный поиск OpenRouter (`openrouter:web_search`): ищет сам OpenRouter внутри запроса к модели,
* для Gemini — через Google Search. `parameters` уходят в API как есть (см. openrouter.ai/docs → Server Tools).
*/
const openRouterWebSearch = {
type: "provider-defined" as const,
id: "openrouter.web_search" as const,
name: "web_search",
args: { parameters: { max_results: 5, max_uses: 2 } },
/** Результат уходит модели и повторяется в каждом её следующем шаге — берём верх выдачи. */
const MAX_RESULTS = 6;
const MAX_NEWS = 3;
/** Готовый ответ Google (блок ответа или карточка знаний), если он есть. */
const answerOf = ({ answerBox, knowledgeGraph }: SerperSearch): string | undefined => {
const answer = answerBox?.answer ?? answerBox?.snippet;
if (answer) return answer;
if (knowledgeGraph?.description) return [knowledgeGraph.title, knowledgeGraph.type, knowledgeGraph.description].filter(Boolean).join(" — ");
return undefined;
};
/** Сводка поиска короткая: она целиком уходит основному агенту и повторяется в каждом его следующем шаге. */
const SEARCH_SUMMARY_TOKENS = 1_000;
/**
* Картинки: со скольких страниц выдачи и сколько с каждой, сколько из Wikimedia Commons и всего.
* Список уходит модели и повторяется в каждом её следующем шаге — держим его коротким.
*/
const IMAGE_PAGES = 3;
const IMAGES_PER_PAGE = 3;
const COMMONS_IMAGES = 4;
const MAX_IMAGES = 8;
interface WebSearchToolDeps {
/** Модель OpenRouter — серверный поиск есть только там. */
model: string;
}
/** Страницы выдачи: сначала источники поиска, потом ссылки из текста сводки (если источников провайдер не дал). */
const pageUrlsOf = (sources: { payload: { url?: string } }[], summary: string): string[] => [
...new Set([
...sources.flatMap(({ payload }) => (payload.url ? [payload.url] : [])),
...(summary.match(/https?:\/\/[^\s)\]>"'«»]+/g) ?? []),
]),
];
/** Не открылась страница или не ответил Commons — просто меньше картинок. */
const orNothing = (promise: Promise<PageImage[]>): Promise<PageImage[]> => promise.catch(() => []);
/** Картинки со страниц выдачи и из Wikimedia Commons, без повторов. */
const collectImages = async (pageUrls: string[], commons: Promise<PageImage[]>): Promise<PageImage[]> => {
const fromPages = await Promise.all(
pageUrls
.slice(0, IMAGE_PAGES)
.map((url) => orNothing(fetchPageImages(url, IMAGES_PER_PAGE).then((page) => page.images))),
);
return uniqueByUrl([...fromPages.flat(), ...(await commons)]).slice(0, MAX_IMAGES);
};
/**
* Поиск в интернете — отдельным агентом Mastra без памяти. Результаты серверного поиска модель видит только
* в запросе, где искала, а основному агенту после поиска нужны ещё шаги (attach_media): сводка как результат
* инструмента остаётся у него до конца ответа. С `imageQuery` инструмент сам собирает картинки — со страниц
* выдачи и из Wikimedia Commons, — чтобы агенту не приходилось выбирать страницы и ходить по ним.
*/
export const createWebSearchTool = ({ model }: WebSearchToolDeps) => {
const searcher = new Agent({
id: "boltun-web-search",
name: "Boltun web search",
instructions: readPrompt("web-search.md"),
model,
tools: { web_search: openRouterWebSearch },
defaultOptions: {
maxSteps: 1,
modelSettings: { maxOutputTokens: SEARCH_SUMMARY_TOKENS },
onError: ({ error }) => console.error("Ошибка провайдера при поиске:", error),
},
});
return createTool({
export const createWebSearchTool = (serper: SerperClient) =>
createTool({
id: "web_search",
description:
"Ищет в интернете (Google): свежие новости и события, факты, цены, всё, чего нет в чате и чего ты не знаешь точно. " +
"Возвращает краткую сводку со ссылками на источники. Нужна картинка или фото — заполни imageQuery: вернутся и прямые " +
"ссылки на картинки с подписями, прикрепи подходящие через attach_media.",
"Ищет в Google: свежие новости и события, факты, цены — то, чего нет в чате и чего ты не знаешь точно. " +
"Возвращает верх выдачи: заголовки, ссылки и короткие фрагменты страниц, готовый ответ Google и новости, если есть. " +
"Картинки ищи через search_images.",
inputSchema: z.object({
query: z.string().min(1).describe("Что найти — запрос своими словами, с уточнениями (что именно, за какой период)."),
imageQuery: z
.string()
.min(1)
.optional()
.describe(
"Только если нужны картинки: что должно быть на картинке, 1–4 слова по-английски, без слов «photo», «image» " +
"(например: capybara, Eiffel Tower night, Elon Musk).",
),
query: z.string().min(1).describe("Запрос как в Google: коротко, по делу, на подходящем языке."),
}),
execute: async ({ query, imageQuery }) => {
execute: async ({ query }) => {
try {
// Commons ищем параллельно с поиском — он не зависит от выдачи.
const commons = imageQuery ? orNothing(searchCommonsImages(imageQuery, COMMONS_IMAGES)) : undefined;
const result = await serper.search(query);
const result = await searcher.generate(query);
const summary = result.text.trim();
const results = (result.organic ?? []).slice(0, MAX_RESULTS).map(({ title, link, snippet, date }) => ({
title,
link,
snippet: [date, snippet].filter(Boolean).join(" — "),
}));
const images = commons ? await collectImages(pageUrlsOf(result.sources, summary), commons) : undefined;
const news = (result.topStories ?? []).slice(0, MAX_NEWS).map(({ title, link, source, date }) => ({
title: [source, date, title].filter(Boolean).join(" · "),
link,
}));
const answer = answerOf(result);
// Ссылки на источники уже в сводке (после каждого факта) — отдельным списком не дублируем.
return {
status: "ok",
summary: summary || "Ничего не нашлось.",
...(images && {
images: images.length > 0 ? images : "Картинок не нашлось — попробуй другой imageQuery.",
}),
status: results.length > 0 || news.length > 0 ? "ok" : "empty",
...(answer && { answer }),
results,
...(news.length > 0 && { news }),
};
} catch (error) {
return { status: "error", result: `Поиск не сработал: ${errorMessage(error)}.` };
}
},
});
};