ИИ: языковая модель (LLM) в серверном коде (ai)
ai — языковая модель проекта. В серверном коде (*.server.ts, Серверные функции)
через него получают ответ, объект заданного типа, разбор картинок, вызовы функций своего сервера и
решение о тексте, а ещё ведут чаты; в приложении у него один метод — ai.messagesResource(id): сообщения чата, живые, пока
пишется ответ. В коде нет ни API-ключа, ни модели: модель — настройка проекта на le.codes, а платит
за неё владелец проекта из своих ИИ-кредитов. API другого провайдера — это fetch из серверного кода,
с ключом в env.
- вызвать LLM с сервера и показать её ответ в приложении (
ai.send) - получить структурированный вывод — JSON заданного типа — вместо текста (
ai.send<T>) - описать фото, которое снял пользователь, прочитать чек или меню (
images) - сделать чат с ИИ-ассистентом, который помнит разговор (
ai.createChat,chat.send) - показывать ответ ассистента, пока он пишется, со строкой «печатает…» (
ai.messagesResource) - дать модели найти заказ или выполнить свой серверный код: function calling, инструменты (
ai.tool) - дать ИИ задать пользователю вопрос с кнопками ответов
- дать ИИ поискать в вебе или прочитать страницу по ссылке и показать источники под ответом (
ai.webSearch,ai.webFetch) - дёшево классифицировать, модерировать, маршрутизировать или оценить текст — спам или нет, какая категория, балл (
ai.decide) - показать, почему ИИ не ответил: нет кредитов, слишком много запросов, дневной лимит (
AiError,RpcError.ai) - протестировать приложение с ИИ на своей машине
Платформы: iOS, Android, веб и веб-плеер — с бэкендом, который задеплоил le.codes: превью
редактора и опубликованное приложение; не на десктопе: desktop run достаёт только до бэкенда на
твоей машине, а упакованная десктопная сборка — ни до какого. У бэкенда на твоей машине (lecodes dev, lecodes test, lecodes render, desktop run)
модели нет: каждый ai.send, ai.decide и chat.send там бросает AiError("unavailable") — см.
Тестирование ИИ на своей машине.
Обзор
// ask.server.ts — выполняется на бэкенде приложения
export async function ask(question: string) {
if (!question.trim()) throw new ApiError(400, "Ask something first")
const reply = await ai.send({
system: "You are a cooking assistant. Answer in two or three short sentences, plain text.",
text: question,
maxTokens: 400,
})
return reply.text
}// main.ts — приложение
import { ask } from "./ask.server"
const asking = action((question: string) => ask(question))
const question = UIInput().style({ placeholder: "How long do I boil an egg?" }).named("question")
const answer = UIText("").named("answer")
UIScreen(
question,
UIButton(UIText(() => (asking.busy.value ? "Thinking…" : "Ask")))
.named("ask")
.onClick(async () => {
const text = await asking(question.value)
if (text !== null) answer.text = text
}),
answer,
UIText(() => asking.error.value?.message ?? "").named("error"), // почему не ответил — см. Ошибки
).style({ gap: 12, padding: 24 }).open()В превью le.codes и в опубликованном приложении ответ появляется под кнопкой. Под lecodes dev
строка ошибки вместо него показывает отказ: ai.send works on a deployed backend only — the model runs on le.codes, paid by the project's owner: deploy the server to use it.
Тестирование ИИ на своей машине: unavailable под lecodes dev, ответы — на le.codes
Под lecodes dev и lecodes test модель не отвечает: она отвечает только на бэкенде, который
задеплоил le.codes, — development (превью редактора, ссылка на проект на телефоне) и production
(опубликованное приложение). У бэкенда на твоей машине пути к ней нет:
- под
lecodes dev,lecodes test,lecodes renderиdesktop runai.sendбросаетAiError("unavailable"), так же иai.decide(ai.decide works on a deployed backend only — …), иchat.send(A chat's answer is written on a deployed backend only — …), который оставляет чат как был. Если его не поймать, вызов приложения падает со статусом 503 иai: "unavailable". Терминал сообщает об этом при первом запросе, а о каждом отклонённом вызове — одной строкой:[server:warn] ask.server.ts#ask: AiError("unavailable") — the call is refused with 503: …; - всё вокруг модели там работает:
ai.createChat,ai.getChat,ai.deleteChat,chat.messages()и, в приложении,ai.messagesResource(id).
Так что на своей машине тестируй то, что приложение делает вокруг модели, — открытие чата, состояния ошибок, повтор, — а сами ответы — в превью le.codes. Флоу может проверить отказ:
{ "steps": [
{ "call": "ask.server.ts#ask", "args": ["hi"], "expect": { "error": { "status": 503 } } },
{ "type": "question", "text": "hi" },
{ "tap": "ask" },
{ "expect": { "node": "error", "text": "deployed backend only" } }
] }Какая модель отвечает и кто платит: Data → AI
Модель — настройка проекта, а не кода: Data → AI в редакторе le.codes. Запрос модель не называет —
ai.send({ model: … }) отклоняется как invalid.
- На плане Free модель — Haiku; платный план может выбрать Sonnet или Opus. Настройка, которую план владельца не разрешает, работает на Haiku.
- Каждый запрос оплачивается из ИИ-кредитов владельца проекта (у командного проекта — из кредитов
команды). Когда их не осталось, запрос бросает
AiError("credits"). - Сколько запросы проекта могут стоить за день (день по UTC), ограничено; Data → AI показывает
сегодняшние траты против этого лимита. Сверх него запрос бросает
AiError("budget")до следующего дня.
Вызов LLM с сервера: ai.send
Чтобы спросить у языковой модели что-то одно из серверного кода — ответить на вопрос, переписать
текст, пересказать заметку, — дождись ai.send в эндпоинте и верни то, что нужно приложению. Чтобы
классифицировать текст — да или нет, категория, тег из списка, оценка, — спрашивай вместо этого
ai.decide: около секунды и малая доля цены send.
await ai.send({
system?: string, // кто такая модель и как ей отвечать
text?: string, // на что она отвечает — и/или
images?: AiImage[], // картинки, на которые она смотрит (см. Картинки), — или
messages?: AiMessage[], // разговор вместо text и images (см. Целый разговор)
tools?: AiTools, // функции, которые она может сначала вызвать (см. Инструменты)
maxTokens?: number, // предел токенов ответа: 1024, если не задан, максимум 4096
}): Promise<AiReply>
type AiReply = {
text: string // ответ
stop: "end" | "length" | "refusal" // готов · обрезан на maxTokens · модель отказалась отвечать
usage: { input: number, output: number } // токены запроса (с system и картинками) и ответа
calls?: AiToolCall[] // вызванные инструменты, по порядку; нет, если не было ни одного
}- Запрос — это
text,imagesили оба — илиmessages, но никогда вместе с ними (invalid). Пустой текст, ключ, которого у запроса нет,maxTokens, который не целое число больше 0:invalid. - Токен — слово или часть слова. Сверх
maxTokensответ обрывается там, где он есть:stopравен"length", аtext— то, что успело написаться.maxTokensбольше 4096 понижается до 4096. stop: "refusal": модель отказалась отвечать; вtext— то, что она сказала, возможно"".- Каждый
ai.send— один платный запрос, он учитывается в частоте вызывающего и в лимитах проекта (Лимиты). Время, которое эндпоинт ждёт модель, не входит в его лимит 30 с. ai.sendничего не стримит: он резолвится целым ответом. Ответ, который приложение показывает по мере написания, — это чат.
Объект вместо текста: ai.send<T> (структурированный вывод)
Чтобы получить данные, которые должна написать модель, — рецепт, список задач, поля чека, — дай
ai.send тип: модель отвечает JSON этого типа, ответ проверяется по нему, и data — значение этого
типа.
Классификация текста — это не сюда. Вердикт — это ai.decide: да или нет (ai.yesNo),
одна категория из нескольких или один тег из списка (ai.choice), несколько тегов (по ai.yesNo на
каждый), оценка (ai.score). Он отвечает вероятностями примерно за секунду, за малую долю цены
типизированного send, и его варианты можно собрать во время выполнения — собственные теги человека, —
чего тип выразить не может.
// recipes.server.ts
export type Recipe = {
title: string
minutes: number
vegetarian: boolean
difficulty: "easy" | "medium" | "hard"
ingredients: { name: string, amount: string }[]
tip?: string // необязательное: модель может его опустить
}
export async function recipeFor(dish: string): Promise<Recipe> {
const { data } = await ai.send<Recipe>({
system: "You write home recipes. Amounts in metric units; minutes = the whole time, preparation included.",
text: dish,
maxTokens: 1500,
})
return data // целый Recipe: ответ проверен по типу
}await ai.send<T>(request): Promise<AiDataReply<T>>
type AiDataReply<T> = { data: T, stop: "end", usage: { input: number, output: number }, calls?: AiToolCall[] }Что может содержать T — JSON, который модели можно велеть написать:
- объект на верхнем уровне (список или строку оберни в объект:
{ items: … }); string,number,boolean,null, массивы, объекты, объединения литералов ("easy" | "hard"),T | null, объединения объектов; свойство с?модель может опустить.
Что валит компиляцию — с файлом, строкой и местом в типе: Date (используй строку, ISO-дату),
Map / Set, класс, функция, File, any / unknown, индексная сигнатура (Record<string, …>:
назови ключи или используй список { key, value }), кортеж, рекурсивный тип, тип шаблонной строки
(template literal), параметр типа, свойство с типом undefined (сделай его необязательным), тип, чья
схема больше 64 КБ:
the type of a typed ai.send and of an ai.tool's arguments is the JSON the model writes — this one cannot be told to it:
recipes.server.ts:12: ai.send<{ when: Date }>: data.when: Date is not JSON — use a string (an ISO date)- Тип — это инструкция для модели: называй каждое свойство по тому, что в нём лежит. Doc-комментарии
до модели не доходят — остальное скажи в
system. - Диапазонов и длин в нём нет:
minutes: numberможет прийти 0 или 900, список — пустым. Проверь то, что важно (data.minutes > 0), прежде чем сохранять. data— всегда целыйT. Ответ, который им не является, бросаетAiError("incomplete"), и сообщение говорит почему: он обрезан наmaxTokens(raise maxTokens), модель отказалась отвечать или написанное не совпало с типом.- Пиши вызов как есть —
ai.send<T>({ … })на глобальномai, с аргументом типа и запросом единственным аргументом: компиляция вписывает схему типа в этот вызов. Вызванный под другим именем (const send = ai.send), он нетипизированный, и в его ответе нетdata. - Инструменты в типизированном вызове можно, если у каждого есть функция; тот, на который отвечает
человек, там —
invalid(Вопрос человеку).
Фото для ИИ: что на нём, прочитать чек — images
Чтобы спросить, что на фото, которое снял пользователь, прочитать чек или проверить картинку, отправь
её в images: File, который эндпоинт получил от приложения, или хранимый файл, прочитанный из базы
данных.
// photos.server.ts
const Dish = model({ name: t.string(), photo: t.image() })
const db = defineDb({ Dish })
export async function whatIsThis(photo: File) { // картинка, которую приложение загружает вместе с вызовом
const reply = await ai.send({ text: "What dish is this? One short sentence.", images: [photo], maxTokens: 200 })
return reply.text
}
export async function caloriesOf(id: number) { // картинка, которая хранится в базе данных
const dish = await db.dish.where({ id }).first()
if (!dish) throw new ApiError(404, "No such dish")
const { data } = await ai.send<{ kcal: number }>({ text: `About how many kcal is this portion of ${dish.name}?`, images: [dish.photo] })
return Math.round(data.kcal)
}// main.ts — приложение выбирает фото и отправляет его с вызовом
import { whatIsThis } from "./photos.server"
UIScreen(
UIButton(UIText("What is this dish?")).named("pick").onClick(async () => {
const photo = await openFilePicker({ accept: "image/*" })
if (photo) toast(await whatIsThis(photo))
}),
).open()- Картинка — это параметр типа
File(загрузка — Хранимые файлы) или значение поляt.file()/t.image(). Что-то другое или файл, который не картинка:invalid. - Не больше 5 картинок на запрос — с
messages5 на все сообщения вместе. - Модель видит каждую как JPEG, повёрнутый так, как задумала камера (HEIC-фото читаются), не больше
1568 px по длинной стороне. Вместе, в таком виде, они занимают не больше 6 МБ: больше —
invalid, отправь меньше. - С картинками
textможно опустить. - Картинки — это вход: они учитываются в
usage.input.
Целый разговор для модели: messages
Чтобы дать модели разговор вместо одного текста — тот, что хранит твой сервер, или историю чата,
прочитанную для пересказа, — передай messages; ответ — следующее сообщение модели.
type AiMessage =
| { role: "user", text?: string, images?: AiImage[] } // текст, картинки или оба
| { role: "assistant", text: string, calls?: AiToolCall[] } // что модель сказала раньше и какие вызовы сделала// summary.server.ts — одно предложение о чате
export async function summarize(id: string) {
const history = await (await ai.getChat(id)).messages()
const reply = await ai.send({
system: "You say what a conversation was about in one sentence.",
messages: [...history.slice(-30), { role: "user", text: "What was this conversation about?" }],
maxTokens: 200,
})
return reply.text
}- Последнее сообщение — пользователя. Не больше 60 сообщений и 5 картинок среди них: из истории чата, где картинок больше, сначала убери старые.
- История чата подходит как есть: остальные ключи
ChatMessage(id,createdAt,writing) модели не передаются. Разговор, который начинается с сообщения ассистента (он поздоровался первым), — это нормально.
Чат с ИИ-ассистентом, который помнит разговор: ai.createChat, chat.send
Чтобы сделать в приложении чат с ИИ-ассистентом — он помнит разговор, платформа хранит его сообщения,
ответ виден, пока пишется, — открой чат на сервере и пиши в него через chat.send. Чат остаётся на
сервере: эндпоинт возвращает его id, а приложение следит за его сообщениями через
ai.messagesResource(id).
// help.server.ts — сервер чата
defineDb({}) // чат хранит свои сообщения в базе данных проекта
const ASSISTANT = { // кто такой ассистент: чат ничего из этого не хранит, поэтому это говорит каждая отправка
system: "You are the cafe's assistant. Answer briefly, in plain text.",
maxTokens: 800,
}
/** Id чата, который называет `id`, или нового, если такого нет (id ещё нет или чата больше нет). */
export async function openHelp(id: string | null): Promise<string> {
if (id) {
try {
return (await ai.getChat(id)).id
} catch (e) {
if (!(e instanceof ApiError)) throw e // 404: чата больше нет, 400: это не id чата — открой новый
}
}
return (await ai.createChat()).id
}
/** Сообщение человека: резолвится, когда ответ сохранён. При отказе чат остаётся как был. */
export async function say(id: string, text: string): Promise<ChatMessage> {
const chat = await ai.getChat(id)
return chat.send({ ...ASSISTANT, text })
}// main.ts — приложение
import { openHelp, say } from "./help.server"
type Opened = { id: string, messages: Resource<ChatMessage[]> }
const savedId = signal<string | null>(null).stored("help-chat") // устройство хранит id чата
const chat = signal<Opened | null>(null)
const list = computed((): ChatMessage[] => {
const loaded = chat.value?.messages.value
return loaded?.state === "ready" ? loaded.data : []
})
const last = computed(() => list.value[list.value.length - 1])
const sending = action((text: string) => say(chat.peek()!.id, text))
const Bubble = (m: ChatMessage) =>
UIText(m.text || "…").style({
alignSelf: m.role === "user" ? "flex-end" : "flex-start", maxWidth: "80%",
px: 12, py: 8, borderRadius: 14, color: "white", bgColor: m.role === "user" ? "#4f7cff" : "#2a3142",
})
const field = UIInput().style({ flexGrow: 1, placeholder: "Message" }).named("message")
const send = async () => {
const text = field.value.trim()
if (!text || !chat.peek() || sending.busy.peek()) return
field.value = ""
if ((await sending(text)) === null) field.value = text // отказ: ничего не изменилось — вернуть текст
}
UIScreen(
UIScrollable(UIColumn(() => list.value.map(Bubble)).style({ gap: 8, padding: 16 })).style({ flexGrow: 1 }),
// ассистент отвечает, пока последнее сообщение — то, что пишется; ни слова ещё нет: "typing…"
UIText(() => (last.value?.writing && !last.value.text ? "typing…" : sending.error.value?.message ?? "")).named("status"),
UIRow(field, UIButton(UIText("Send")).named("send").onClick(send)).style({ gap: 8, padding: 16 }),
).style({ bgColor: "#1e2230" })
.onClose(() => chat.peek()?.messages.close()) // перестать следить
.open()
const main = async () => {
const id = await openHelp(savedId.peek())
savedId.value = id
chat.value = { id, messages: ai.messagesResource(id) } // сообщения чата, живые
}
main()Сообщение человека появляется, когда сервер его сохранил, под ним — ответ, пока модель его пишет, и этот ответ остаётся одним сохранённым сообщением. Сторона сервера:
await ai.createChat(): AiChat // новый чат, его строка записана: chat.id можно сохранять
await ai.getChat(id): AiChat // чат, который называет id, — ApiError 400: не id чата, 404 "No such chat"
await ai.deleteChat(id): boolean // true: удалён, а с ним его сообщения и картинки; false: такого не было
await chat.send({ system?, tools?, text?, images?, maxTokens? }): ChatMessage // ответ, когда он сохранён
await chat.messages(): ChatMessage[] // все сохранённые сообщения, по порядку
chat.id: string // UUID — то, что эндпоинт возвращает приложению
type ChatMessage = {
id: number | string // растёт по ходу разговора; "writing" у ответа, который пишется
role: "user" | "assistant"
text: string // "" для одних картинок, для ответа, который только вызывал инструменты, и в начале хода
images: StoredImage[] // картинки пользователя, как они сохранены; у ответа их нет
calls?: AiToolCall[] // вызовы инструментов в ответе; нет, если не было ни одного
createdAt: number // когда сохранено, мс с 1970
writing: boolean // ответ, который пишется (только в списке приложения); false у каждого сохранённого
}-
Чат хранит сообщения в базе данных проекта, в двух моделях платформы, которые добавляет компиляция (
AiChat,AiChatMessage: это неdb.<model>, и ни одна твоя модель не может взять их имена). Проекту, который открывает чаты, нуженdefineDb(…)в серверном файле —defineDb({}), если моделей у него нет. Без него его бэкенд не стартует:a chat (ai.createChat, ai.getChat, ai.deleteChat) keeps its conversation in the project's database, and this project defines none — …. -
Эти три метода отвечают промисом, и их ждут через
awaitтам, где вызывают.ai.getChat(id).id, вызов отдельной инструкцией или промис, отложенный на потом, валят компиляцию:a chat's verb is awaited — ai.createChat, ai.getChat and ai.deleteChat answer a promise: help.server.ts:4: ai.getChat(…) — write `await` before it -
Опций они не принимают (
ai.createChat({ system })бросает): кто такой ассистент, говорит каждая отправка.
Кто такой ассистент: говорится при каждой отправке
Чат хранит только сообщения. system, tools и maxTokens принадлежат каждому chat.send: держи их
в одной константе модуля и разворачивай её в каждую отправку — chat.send({ ...ASSISTANT, text }).
Изменение константы доходит до каждого чата с его следующим ответом. Одна отправка может что-то к ней
добавить:
chat.send({ ...ASSISTANT, system: ASSISTANT.system + "\nThis is the last question.", tools: { ...ASSISTANT.tools, finish }, text })
— где finish — инструмент, созданный в эндпоинте, который видит значения этого вызова.
Один ход: chat.send ждёт, всё или ничего
chat.send — это ai.send, который помнит разговор: он сохраняет сообщение пользователя (text,
images или оба), спрашивает модель с историей чата и инструментами этой отправки, сохраняет ответ и
резолвится им.
- Всё или ничего. Когда
sendрезолвится, в чате оба сообщения. Когда бросает —AiErrorилиApiError(404), потому что чат тем временем удалили, — от хода в чате ничего нет: сообщение пользователя и его картинки забраны обратно. Что тем временем сделал инструмент, остаётся сделанным. Чтобы спросить снова, снова вызовиsend. - Ни
text, ниimages: ассистент говорит сам — приветствие в новом чате, продолжение посреди чата. Сохраняется только его ответ, и он считается одним из сообщений дня.text: ""— это другое: это пустое сообщение, его отклоняют с 400. - Ответ, обрезанный на
maxTokens, сохраняется как есть. Ход, в ответе которого нет ни текста, ни вызовов, бросаетAiError("incomplete"). - Один ход на чат за раз:
send, пока идёт другой, отклоняется сApiError(409),An answer is being written in this chat — wait for it to end. - Сообщение — не больше 8000 символов и 5 картинок, иначе
ApiError(400). Картинки чата — этоFile, которые получил вызов (хранимый файл принадлежит своей строке и отклоняется); хранятся они так же, как у поляt.image()(Картинки). - Модель получает последние 30 сохранённых сообщений чата — вызовы ответов с их результатами в их
числе — и 5 самых новых картинок. Что старше, она не видит: долговечные факты держи в
systemили за инструментом. - Вызов эндпоинта ждёт столько, сколько пишется ответ; это ожидание не входит в его лимит 30 с. Приложение, которое тем временем ушло, ничего не останавливает: ответ сохраняется.
- Деплой или перезапуск бэкенда посреди хода забирает ход обратно: вызов отклоняется (502
incomplete,The answer was not written — ask again, или 503), и чат остаётся как был.
Ответ ИИ, пока он пишется: сообщения чата, ai.messagesResource(id)
Чтобы показать чат на экране — его сообщения и ответ, пока модель его пишет, — эндпоинт возвращает id
чата (chat.id, строку), а приложение открывает ai.messagesResource(id): resource сообщений чата,
живой, того же рода, что .resource() у computed.
const messages = ai.messagesResource(chatId) // Resource<ChatMessage[]> — chatId: то, что вернул эндпоинт
messages.value: Loaded<ChatMessage[]> // loading → ready: последние 200 сохранённых, последним — ответ, который пишется · failed
messages.peek(): Loaded<ChatMessage[]> // то же, прочитанное без отслеживания
messages.reload() // снова следить: после close() (onOpen экрана) или после ошибки
messages.close() // перестать следить (onClose экрана)- Список — серверный. Сообщение пользователя появляется, когда оно сохранено. От начала хода до его
конца ПОСЛЕДНЕЕ сообщение — ответ, который пишется:
id: "writing",writing: true, егоtextсначала"", а потом растёт, егоcalls— по мере работы инструментов, — а когда ход заканчивается, его место занимает сохранённый ответ. Ход, который не получил ответа, снова убирает из списка и сообщение, и пишущийся ответ. - «Отвечает ли ассистент» — это
writingпоследнего сообщения: показывай «печатает…», пока он true, а егоtextвсё ещё"". failed, когда сервер отказывает: 404No such chat(чата с таким id нет или его удалили черезai.deleteChat), 400, когда id — не UUID. Открытие никогда не бросает.- Каждый вызов — отдельная подписка: открывай её там, где строится экран, который показывает чат, и
вызывай
close(), когда экран закрывается;reload()снова начинает следить. - Он только читает:
sendу него нет. Приложение пишет через твои эндпоинты, а прошло ли сообщение, говорит ответ этого вызова —errorуaction, а не список. - Он ездит по сокету каналов: после переподключения или деплоя показывает чат таким, каким его держит сервер.
- Сам объект чата никогда не покидает сервер. Эндпоинт, который его возвращает, computed, чьё значение
его держит, сообщение канала, которое его несёт, отклоняются с 500 — словами, которые говорят, что
делать:
the answer of help.server.ts#openHelp holds a chat (result) — a chat stays on the server: return its id, chat.id, and the app follows it with ai.messagesResource(id). ai— одно имя на обеих сторонах, и у каждой стороны свои методы:ai.messagesResource— у приложения, аai.send,ai.toolи методы чата — у сервера. Компиляция отклоняет метод не на своей стороне, с файлом и строкой:ai.messagesResource is the app's — on the server read a chat with ai.getChat(id),ai.send runs on the server — call an endpoint.
Хранить, защищать и удалять чат: его id
chat.id — то, что ты хранишь, чтобы снова открыть чат: поле t.uuid() строки, которой принадлежит
чат, или хранилище устройства (signal(null).stored(key)), — и отдаёшь обратно эндпоинту, который
вызывает ai.getChat(id).
- Id — это право читать чат: кто его знает, тот может за ним следить (
ai.messagesResource(id)). Эндпоинт возвращает его только тому, кто может читать чат, и пишет только после проверки вызывающего — находи чат через строку вызывающего, а не принимай любой id:
// chats.server.ts — разговоры каждого пользователя, и ничьи больше
const User = model({ name: t.string().default("") })
const Conversation = model({ owner: t.one("User").onDelete("cascade"), chat: t.uuid().unique() })
const db = defineDb({ User, Conversation }).withAuth({ model: "User" })
const ASSISTANT = { system: "You are a helpful, concise assistant.", maxTokens: 1024 }
/** Разговор `id` вызывающего — чужой «не найден», как и тот, которого никогда не было. */
const mine = async (id: number) => {
const me = await db.auth.requireUser().select({ id: true })
const row = await db.conversation.where({ id, owner: { id: me.id } }).first()
if (!row) throw new ApiError(404, "No such conversation")
return row
}
/** Новый разговор вызывающего: id нашей строки и id чата — только его владельцу. */
export async function newConversation(): Promise<{ id: number, chat: string }> {
const me = await db.auth.requireUser().select({ id: true })
const chat = await ai.createChat()
const { id } = await db.conversation.insert({ owner: me, chat: chat.id })
return { id, chat: chat.id }
}
export async function sendMessage(id: number, text: string): Promise<ChatMessage> {
const row = await mine(id)
return (await ai.getChat(row.chat)).send({ ...ASSISTANT, text })
}
export async function deleteConversation(id: number) {
const row = await mine(id)
await ai.deleteChat(row.chat) // false, если его уже не было: это не ошибка
await db.conversation.delete(row.id)
}- Чат живёт до
ai.deleteChat(id). Чат без единого сообщения платформа удаляет через день после создания — в том числе чат, чьё единственное сообщение было забрано обратно. Поэтому сохранённого id может уже не быть:getChatотклоняется с 404; поймай это и вызовиcreateChat. ai.deleteChat(id)удаляет чат, его сообщения и их картинки. Для id, который не называет ни одного чата, он резолвится вfalse, так что вызвать его дважды безопасно; id, который не UUID, —ApiError(400).sendэтого чата, который ждёт ответа, отклоняется с 404, аai.messagesResource(id)этого чата в приложении становитсяfailed, 404No such chat.
Модель вызывает твой код: инструменты, ai.tool (function calling)
Чтобы модель могла что-то найти или сделать, пока отвечает, — найти заказ, проверить остатки, сохранить результат, — дай ей инструменты: функции твоего сервера, у каждой описание и типизированный параметр. Модель вызывает их, читает, что они вернули, и отвечает, когда у неё есть всё нужное.
// orders.server.ts
const Order = model({ number: t.string().unique(), status: t.string(), total: t.float() })
const db = defineDb({ Order })
const findOrder = ai.tool(
"Find one of the cafe's orders by its number: its status and its total",
async ({ number }: { number: string }) => {
const order = await db.order.where({ number }).select({ status: true, total: true }).first()
if (!order) throw new ApiError(404, `There is no order ${number}`) // это сообщение читает модель
return order
},
)
export async function askAboutOrders(question: string) {
const reply = await ai.send({
system: "You answer questions about the cafe's orders. Look an order up before you say anything about it.",
text: question,
tools: { findOrder }, // ключ — имя, под которым модель его вызывает
maxTokens: 500,
})
return { text: reply.text, lookedUp: reply.calls?.length ?? 0 }
}ai.tool(description: string, fn: (args: A) => unknown): AiTool // на вызов отвечает код
ai.tool<A>(description: string): AiTool // на него отвечает человек — см. Вопрос человеку
tools: { findOrder, ask } // в ai.send и chat.send: ключ — имя инструмента
type AiToolCall = { tool: string, args: unknown, result?: unknown, error?: string }- Описание — то, что модель читает, чтобы решить, когда его вызвать (не больше 10 000 символов).
- Функция принимает ОДИН объект аргументов, типизированный, — или ничего (
() => Date.now()). Модели сообщается JSON этого типа, по правиламai.send<T>; параметр без типа, два параметра или не объект валят компиляцию:ai.tool: a tool's function takes ONE object of arguments — …. - То, что она возвращает, синхронно или асинхронно, уходит модели как JSON: любое значение, не больше 16 КБ в JSON (результат крупнее — ошибка, о которой сообщают модели).
- Брошенное исключение слышит модель, и она продолжает: сообщение
ApiError— как есть, любую другую ошибку — какThe tool failed(сама ошибка — в консоли сервера). С аргументами, которые не совпадают с типом, функция не выполняется; модели говорят почему. - Инструмент выполняется там, где сделана отправка, в вызове эндпоинта:
requestиdb.auth— того, кто вызывает. Инструмент, созданный внутри эндпоинта, видит значения этого вызова. - Вызовы одного ответа выполняются один за другим. Одна отправка может спросить модель 8 раз и
выполнить 24 вызова — сверх любого из этих пределов она бросает
AiError("incomplete").text— всё, что модель написала между вызовами,usage— сумма,maxTokens— на каждый вызов модели; в частоте вызывающего отправка считается один раз. reply.callsперечисляет вызовы в порядке выполнения, каждый со своимresultилиerror.- Что сделал инструмент, остаётся сделанным, если отправка после этого упала, — в чате тоже.
- Имя — ключ в
tools: буквы, цифры,_и-, не больше 64; 16 инструментов на запрос. - Создавай инструмент через
ai.tool(…)на глобальном имени, в серверном файле: компиляция вписывает его схему в этот вызов. Инструмент, которого она не видела, бросаетai.tool: this tool has no schema of its arguments — ….
Вызовы инструментов в чате — часть чата
В чате ответ сохраняется со своими calls — их аргументами и результатами, — и их видит каждый, кто
следит за чатом; ai.messagesResource(id) показывает каждый вызов, пока он выполняется (ещё без
result), а потом — с результатом. На следующих ходах модель получает их снова. Возвращай то, что
может лежать в разговоре: поля, нужные ответу, а не строку целиком.
Вопрос человеку с кнопками ответов: инструмент без функции
Чтобы модель могла спросить пользователя — викторина, интервью при онбординге, «что из этого ты имел в
виду?» с кнопками, — дай ей инструмент без функции: ai.tool<T>(description). Его вызов заканчивает
ход ассистента, приложение показывает его аргументы, а следующее сообщение человека — ответ на него.
// quiz.server.ts — модель спрашивает, человек отвечает кнопкой (или пишет текстом)
export type Ask = { question: string, options: string[] }
const ask = ai.tool<Ask>("Ask the user one question, with 2 to 4 short answers they can tap") // без функции: отвечает человек
const QUIZ = {
system: "You run a five-question quiz about the solar system. Ask every question with the ask tool, never in your text. " +
"After each answer say in a few words whether it was right. After the fifth, give the score and ask nothing more.",
tools: { ask },
maxTokens: 400,
}
export async function startQuiz(): Promise<string> {
const chat = await ai.createChat()
await chat.send({ ...QUIZ }) // без текста: ассистент говорит первым — и спрашивает
return chat.id // приложение следит за ним: ai.messagesResource(id)
}
export async function answerQuiz(id: string, text: string) {
const chat = await ai.getChat(id)
await chat.send({ ...QUIZ, text }) // ответ на ждущий вопрос: для модели — его результат
}// main.ts — приложение
import { answerQuiz, startQuiz, type Ask } from "./quiz.server"
type Opened = { id: string, messages: Resource<ChatMessage[]> }
const chat = signal<Opened | null>(null)
const messages = computed((): ChatMessage[] => {
const loaded = chat.value?.messages.value
return loaded?.state === "ready" ? loaded.data : []
})
const replying = action((text: string) => answerQuiz(chat.peek()!.id, text))
/** Вопрос, который ждёт человека: вызов `ask` без result и без error в последнем сохранённом сообщении. */
const waiting = computed((): Ask | null => {
const last = messages.value[messages.value.length - 1]
if (last?.role !== "assistant" || last.writing) return null // пока ответ пишется, вызов ещё выполняется
const call = last.calls?.find((c) => c.tool === "ask" && c.result === undefined && c.error === undefined)
return call ? (call.args as Ask) : null
})
UIScreen(
UIColumn(() => messages.value.filter((m) => m.text).map((m) => UIText(`${m.role === "user" ? "You" : "Quiz"}: ${m.text}`))),
UIText(() => waiting.value?.question ?? "").style({ fontSize: 20 }).named("question"),
UIRow(() => (waiting.value && !replying.busy.value ? waiting.value.options : []).map((option, i) =>
UIButton(UIText(option)).named(`option-${i + 1}`).onClick(() => replying(option)),
)).style({ gap: 8, flexWrap: "wrap" }),
UIText(() => replying.error.value?.message ?? ""),
).style({ gap: 12, padding: 24 })
.onClose(() => chat.peek()?.messages.close())
.open()
startQuiz().then((id) => { chat.value = { id, messages: ai.messagesResource(id) } })- Инструмент с функцией: отвечает код. Инструмент без неё: отвечает человек.
T— его аргументы, объектный тип по правиламai.send<T>: то, что заполняет модель и показывает приложение.ai.tool("…")без функции и без аргумента типа, как и аргумент типа рядом с функцией, валят компиляцию. - Когда ответ модели его вызывает, инструменты с функцией, вызванные в том же ответе, всё равно
выполняются по порядку, а затем ход заканчивается — модель больше не спрашивают.
chat.sendрезолвится сохранённым ответом: его текстом (тем, что модель написала до вызова, возможно"") и егоcalls, где у этого вызова нет ниresult, ниerror. - Следующий
chat.send({ ...QUIZ, text })— ответ на него, будь то нажатый вариант или набранный текст. Модель получает это сообщение как результат вызова; в чате это обычное сообщение пользователя. Картинки, отправленные с ним, идут вместе с ним; отправка без текста отвечает на него строкой "no message". Если таких вызовов в одном ответе несколько, это одно сообщение отвечает на все. - Отправка, которая отвечает, несёт тот же инструмент (разверни ту же константу). Без него модель получит сообщение человека как обычное — после вызова, на который никто не ответил.
- В приложении ждущий вопрос — это вызов без
resultи безerrorв ПОСЛЕДНЕМ сообщении чата, когда оно сохранено (!writing): пока ответ пишется, вызов без результата — это инструмент, который ещё выполняется. - Аргументы, которые не совпадают с
T, — результат-ошибка, как у любого инструмента, и модель продолжает. - С
ai.sendответ заканчивается так же (stop: "end", вызов ждёт вcalls). Верни разговор с ответом человека после него — и снова инструмент:
export type Pick = { question: string, options: string[] }
const pick = ai.tool<Pick>("Ask the user to choose one option")
export async function nextTurn(first: string, said: AiReply, answer: string) {
return ai.send({
tools: { pick },
messages: [
{ role: "user", text: first },
{ role: "assistant", text: said.text, calls: said.calls },
{ role: "user", text: answer }, // для модели — результат ждущего вызова
],
})
}- Типизированный
ai.send<T>не принимает инструмент без функции: его ответ — данные, а такой вызов закончил бы его без них (invalid).
Поиск в вебе и чтение страницы: ai.webSearch(), ai.webFetch()
Для того, чего модель не знает, — сегодняшние новости, цена, страница товара, статья, на которую дал ссылку пользователь, — дай ей веб-инструменты. Их выполняет Anthropic на своих серверах: ни функции, ни описания, только инструмент под тем именем, которым его называет твоё приложение.
// support.server.ts
const SUPPORT = {
system: "You help the cafe's customers. Search the web for anything about the area; read a page when the customer sends a link.",
tools: { findOrder, search: ai.webSearch(), page: ai.webFetch() }, // findOrder: твой собственный инструмент, рядом с ними
maxTokens: 800,
}
export async function ask(id: string, text: string) {
await (await ai.getChat(id)).send({ ...SUPPORT, text })
}
export async function quick(question: string) {
const reply = await ai.send({ ...SUPPORT, text: question })
return { text: reply.text, sources: reply.sources ?? [] } // показывай источники вместе с ответом
}ai.webSearch(options?: AiWebOptions): AiWebTool
ai.webFetch(options?: AiWebOptions): AiWebTool
type AiWebOptions = { maxUses?: number, allowedDomains?: string[], blockedDomains?: string[] }
type AiSource = { url: string, title: string }- Они идут в тот же объект
tools, и вai.send, и вchat.send, рядом с твоими инструментами — по одному каждого на отправку. Ключ — твоё имя для него;web_searchиweb_fetch— собственные имена модели для них, так что твой инструмент эти ключи взять не может. - Их вызовы лежат в
calls, как любые другие, под твоим ключом — но никогда не сама страница:- поиск:
{ tool: "search", args: { query }, result: { sources: [{ url, title }] } }— найденные страницы (пустой список, если ничего не нашлось); - страница:
{ tool: "page", args: { url }, result: { url, title? } }; - любой из них с
errorвместоresult, если не удался, — код Anthropic:max_uses_exceeded,too_many_requests,url_not_accessible,url_not_in_prior_context,unsupported_content_type,unavailable, … Модель это слышит и продолжает.
- поиск:
sources— вreply.sourcesи у сохранённого ответа чата — это страницы, которые цитирует текст ответа, каждая один раз, в порядке первого цитирования; их нет, если он ничего не цитирует (модель может искать и всё равно ничего не процитировать: что нашлось, говоритresult.sourcesпоиска). Условия Anthropic: когда показываешь ответ людям, показывай вместе с ним его источники.- Пока ответ чата пишется, веб-вызов ещё без
result— это идущий поиск: показывай «Ищу в вебе…». У веб-вызовов сохранённого ответа всегда естьresultилиerror. - Страница читается только по ссылке, которая уже есть в разговоре: в сообщении пользователя, в
результате инструмента, среди страниц более раннего поиска — никогда по ссылке, которую модель
написала сама, и не по ссылке, которая есть только в
system. Ссылку, которую модель должна прочитать, клади в сообщение пользователя:text: `${question}\n\n${url}`. Страницы, которым для отрисовки нужен JavaScript, не читаются. maxUses: сколько поисков (или страниц) может сделать одна отправка — 3, если не задано, не больше 5.allowedDomainsилиblockedDomains(не оба сразу): голые домены с необязательным путём, без схемы —"docs.example.com","example.com/blog"— не больше 20. Неверная опция бросает в самом вызовеai.webSearch(…)/ai.webFetch(…):ai.webSearch: maxUses is at most 5 uses in one send, got 6.- Сколько это стоит владельцу: поиск — около $0.01 сверх токенов, которые занимают его результаты; чтение страницы стоит её токенов — до примерно 20 000 со страницы. И то и другое учитывается в дневном лимите проекта.
- Чат хранит текст ответа, его вызовы и его источники — но не страницы: следующие ходы их снова не получают (и снова за них не платят). Модель видит текст своего прошлого ответа.
- Типизированный
ai.send<T>не принимает веб-инструмент (invalid): API не умеет цитировать страницы в типизированном ответе. Ищи в одной отправке, а типизированный ответ проси в другой — с текстом первого ответа в еёtext.
// main.ts — ответ, "Searching the web…", пока идёт поиск, и источники под ним
const messages = ai.messagesResource(chatId)
const list = computed((): ChatMessage[] => (messages.value.state === "ready" ? messages.value.data : []))
const bubble = (m: ChatMessage) => {
const searching = m.writing && (m.calls ?? []).some((c) => c.tool === "search" && c.result === undefined && c.error === undefined)
return UIColumn(
UIText(m.text),
...(searching ? [UIText("Searching the web…").style({ color: "#888" })] : []),
...(m.sources ?? []).map((s, i) => UIText(`[${i + 1}] ${s.title}`).style({ color: "#2563eb" }).onClick(() => openURL(s.url))),
).style({ gap: 4 })
}
UIScreen(UIColumn(() => list.value.map(bubble)).style({ gap: 12 })).style({ padding: 16 }).open()Классифицировать, модерировать, маршрутизировать или оценить текст с ИИ: ai.decide (спам, категория, тональность, оценка)
Чтобы классифицировать текст с помощью ИИ — модерация контента (спам ли этот комментарий, токсичный ли
он или оскорбительный), категория или тег сообщения, в какую команду направить обращение в поддержку,
анализ тональности, оценка по шкале, — спроси модель решений платформы через ai.decide. Текста
она не пишет: на вопрос одного из видов она отвечает тем, насколько вероятен каждый ответ, примерно за
секунду и за малую долю стоимости ai.send.
// reviews.server.ts
const Review = model({ text: t.string(), topic: t.string().default(""), hidden: t.boolean().default(false) })
const db = defineDb({ Review })
export async function addReview(text: string) {
if (!text.trim()) throw new ApiError(400, "Write something first")
const { spam, topic } = await ai.decide(text, {
spam: ai.yesNo("Is this review spam or an advertisement?", {
yes: "Advertising, links, the same text repeated",
no: "An opinion about the cafe, even a rude one",
}),
topic: ai.choice("What is the review mostly about?", {
food: null, // всё сказано именем
service: "Staff, waiting time, delivery",
price: null,
}),
})
return db.review.insert({
text,
hidden: spam.probability > 0.8, // свой собственный порог
topic: topic.confidence > 0.5 ? topic.choice : "", // topic.choice: "food" | "service" | "price"
})
}// классификация текста: вердикт с вероятностями, ~1 с, намного дешевле ai.send или типизированного ai.send<T>
await ai.decide(text: string, question: AiQuestion): the question's answer
await ai.decide(text: string, questions: { name: AiQuestion, … }): { name: that question's answer, … }
ai.yesNo(question: string, criteria?: { yes?: string, no?: string }) → { probability: number }
ai.choice(question: string, options: { name: string | null, … }) → { choice: name, confidence: number, probabilities: { name: number, … } }
ai.score(question: string, levels: string[]) → { score: number, confidence: number, probabilities: number[] }- Несколько тегов из списка — по вопросу да / нет на каждый, в одном decide —
ai.decide(note, Object.fromEntries(tags.map((tag) => [tag, ai.yesNo(`Does the note fit the tag "${tag}"?`)])))— и теги выше твоего порога — теги заметки; один тег — этоai.choiceпо ним. - Один вопрос отвечает своим ответом:
const spam = await ai.decide(text, ai.yesNo("Is it spam?")), потомspam.probability. Несколько передаются по именам и отвечают под теми же именами — один запрос, одна оплата текста, каждый вопрос задаётся тексту отдельно (один ничего не говорит другому). ai.yesNo→probability: насколько вероятно, что ответ «да», 0 … 1. Критерии говорят, что считается «да», а что «нет», там, где вопрос оставляет простор, — любой из них, оба или ни одного. Это то, насколько модель УВЕРЕНА, а не «насколько сильно»: «Клиент злится?» с 0.9 — это «почти наверняка злится», а не «очень злится». Степень — этоai.score.ai.choice→choice: имя самого вероятного варианта;probabilities: вероятность каждого варианта, по имени (вместе около 1);confidence: насколько выбор впереди остальных, 0 (все одинаковы) … 1. Вариант — это его имя и описание илиnull, когда имя говорит само за себя; от 1 до 255 вариантов.ai.score→score: где текст находится на уровнях — 0 это первый, дробный (1.7: между вторым и третьим;Math.round(score)— индекс уровня);probabilities: вероятность каждого уровня, по порядку;confidence: насколько плотно они собраны вокруг одного уровня. Уровни описываются от низшего, от 2 до 10. Одна вещь — одна оценка: «полезный» и «вежливый» — это два вопроса.- Тип ответа следует из вызова:
choice— объединение имён вариантов, написанных в вызове, уprobabilitiesровно эти ключи, а у ответов — имена вопросов. Варианты, собранные во время выполнения (Record<string, string | null>из строк таблицы), работают так же;choiceтогда —string. - Модель всегда отвечает — «не знаю» у неё нет, и choice всегда выбирает один из вариантов. Действуй
выше своего порога (
probability > 0.8,confidence > 0.5), а остальное считай нерешённым; для «ничего из этого» задайai.yesNoрядом с choice («Упоминается ли тут какая-нибудь из этих тем?»). - Задавай узкие вопросы: по одной вещи, на которую можно ответить по одному только тексту. Суждение
из нескольких факторов — это несколько вопросов, сложенных в коде. Что требует рассуждения по шагам
или слов — объяснение, пересказ, ответ, — это
ai.send. text— строка, не больше 200 000 символов, — объект передавай какJSON.stringify(value). Сама модель принимает около 64 000 токенов на запрос и 32 000 с любым одним вопросом; сверх этого вызов бросаетAiError("invalid"). Не больше 32 вопросов на decide; вопрос — до 10 000 символов, критерий (что считается «да», описание варианта, уровень) — до 2 000.- Неверный аргумент
ai.yesNo/ai.choice/ai.scoreбросает там, где создаётся вопрос (ai.score: a score has 2 to 10 levels, got 1); вопрос можно создать один раз, на верхнем уровне модуля, и задавать много раз. - Какая модель решает — дело платформы: одна для всех проектов и планов, а не настройка Data → AI:
Jev от TypeSafe, и текст с вопросами отправляются в TypeSafe. Владелец платит за токены текста и
вопросов (ответы ничего не стоят) из тех же ИИ-кредитов и в рамках того же дневного лимита, что и
ai.send. - Он бросает тот же
AiError, что иai.send, —credits,budget,busy,unavailable(в том числе на бэкенде на твоей машине:ai.decide works on a deployed backend only — …),invalid, — и непойманный так же отклоняет вызов приложения (Ошибки). Один decide — один запрос в частоте вызывающего, сколько бы вопросов он ни задавал. - Он не принимает ни картинок, ни
system, ни инструментов и не входит в чат: решай в эндпоинте, до или послеchat.send. - Где решение необязательно, лови отказ и продолжай без него — отзыв сохраняется без сортировки,
сообщение уходит команде по умолчанию. Тогда приложение работает и на бэкенде без модели
(
lecodes dev, проверка), где каждый decide —unavailable:
const decided = async <Q extends AiQuestion | Record<string, AiQuestion>>(text: string, question: Q): Promise<AiAnswers<Q> | null> => {
try {
return await ai.decide(text, question)
} catch (e) {
if (e instanceof AiError && e.code !== "invalid") return null // на этот раз без решения
throw e
}
}
const spam = await decided(text, ai.yesNo("Is this review spam?"))
const hidden = spam !== null && spam.probability > 0.8 // не решено: показан, как раньше// support.server.ts — направить сообщение, прежде чем на него ответить
const DEPARTMENT = ai.choice("Which team handles this message?", {
billing: "Payments, refunds, invoices",
delivery: "Where the order is, a late or damaged order",
other: "Anything else",
})
export async function route(message: string) {
const team = await ai.decide(message, DEPARTMENT) // один вопрос: его ответ
return team.confidence > 0.6 ? team.choice : "other"
}Когда ИИ не отвечает: кончились кредиты, дневной лимит, перегрузка — AiError, RpcError.ai
Когда модель не даёт ответа — у владельца кончились кредиты, дневной лимит исчерпан, слишком много
запросов, — ai.send, ai.decide и chat.send бросают AiError: его code — причина, на которую код
может отреагировать, его message — слова. Эндпоинт, который его не ловит, отклоняет вызов
приложения со статусом этого кода, а приложение читает код как ai.
class AiError extends Error { readonly code: AiErrorCode } // сервер: что бросают ai.send и chat.send
err.ai?: AiErrorCode // приложение: у RpcError — и у Failure в action / resourcecode |
почему | вызов приложения, если не поймать |
|---|---|---|
credits |
у владельца проекта не осталось ИИ-кредитов | 402 |
budget |
дневной ИИ-лимит проекта исчерпан (Data → AI) | 402 |
busy |
слишком много запросов: этого вызывающего, проекта (8 одновременно) или платформы — тот же запрос можно отправить чуть позже | 429 |
unavailable |
модель не ответила: бэкенд на твоей машине, или не ответила платформа (или её веб-инструменты выключены: отправка с ai.webSearch() / ai.webFetch()) |
503 |
incomplete |
нет целого ответа: типизированный ответ, который не целый T; ответ чата, который не был написан; модель всё ещё вызывает инструменты после 8 раундов или 24 вызовов |
502 |
limit |
только chat.send: человек отправил столько сообщений, сколько разрешено за день (100) |
429 |
invalid |
запрос неверный — ошибка твоего кода, сообщение говорит какая | 500 Internal error, без ai |
- Непойманный
AiError— не падение: вызов отклоняется словамиAiError, его код — вRpcError.aiприложения, а консоль сервера сообщает об этом одной строкой.invalid— 500, как любое исключение, его сообщение — только в консоли сервера. - Хук канала и прогон computed, из которых он вырвался, несут
aiтак же (errorподписки,failedу resource). - 429 без
ai— этоToo many callsтранспорта (Лимиты). - Остальные отказы чата —
ApiErrorбезai: 400 (пустое или слишком длинное сообщение, не id чата), 404 (No such chat), 409 (идёт ход).
В приложении ветвись по ai и говори человеческими словами:
// main.ts
import { ask } from "./ask.server"
const asking = action((question: string) => ask(question))
const said = (f: Failure): string => {
if (f.offline) return "No connection"
switch (f.ai) {
case "limit": return "That's all for today — come back tomorrow"
case "busy": return "Too many questions at once — try again in a few seconds"
case "credits": case "budget": return "The assistant is resting until tomorrow"
case "unavailable": case "incomplete": return "The assistant could not answer — try again"
}
return f.message // ApiError эндпоинта
}
UIScreen(
UIButton(UIText("Ask")).named("ask").onClick(() => asking("What is on the menu today?")),
UIText(() => (asking.error.value ? said(asking.error.value) : "")).named("error"),
).open()На сервере лови его там, где ответ необязателен:
export async function suggestTitle(text: string): Promise<string | null> {
try {
const { data } = await ai.send<{ title: string }>({ system: "Name the note in 2 to 6 words.", text, maxTokens: 60 })
return data.title
} catch (e) {
if (e instanceof AiError && e.code !== "invalid") return null // на этот раз без заголовка: заметка всё равно сохраняется
throw e
}
}Лимиты
Что может ИИ проекта и что даёт каждый лимит, когда его превысили:
| что | лимит | сверх него |
|---|---|---|
| запросы одного вызывающего — устройства: по его сессии, по его адресу, пока сессии нет | один раз в 5 с, всплеск 5 | busy |
| запросы серверного кода, за которыми нет вызова (таймер, загрузка модуля) | одно ведро на все, та же частота | busy |
| одновременные запросы проекта (ход чата в их числе) | 8 | busy |
| сколько стоят запросы проекта за день (UTC) | дневной лимит, который показывает Data → AI | budget |
| ИИ-кредиты владельца | сколько осталось | credits |
| токены ответа, на каждый вызов модели | maxTokens: 1024, если не задан, не больше 4096 |
stop: "length"; типизированный: incomplete |
text / system запроса |
400 000 / 200 000 символов | invalid |
сообщения ai.send({ messages }) |
60 | invalid |
| картинки запроса | 5; каждая показывается не больше чем в 1568 px; вместе 6 МБ | invalid |
| схема типизированного ответа | 64 КБ в JSON | ошибка компиляции |
| инструменты запроса | 16, веб-инструменты в их числе; описание — 10 000 символов | invalid |
| одна отправка с инструментами | 8 вызовов модели (продолжение приостановленного длинного хода — тоже в их числе), 24 вызова твоих инструментов | incomplete |
| веб-инструменты запроса | один ai.webSearch(), один ai.webFetch() |
invalid |
| использования веб-инструмента за одну отправку | maxUses: 3, если не задан, не больше 5; список доменов — не больше 20, только один список |
бросается в ai.webSearch(…) / ai.webFetch(…); сверх maxUses у вызова error — max_uses_exceeded |
| страница, которую читает модель | около 20 000 её токенов | остальное обрезается |
типизированный ai.send<T> с веб-инструментом |
не разрешён | invalid |
| результат инструмента | 16 КБ в JSON | модели сообщают, что вызов упал |
текст ai.decide |
200 000 символов; около 64 000 токенов вместе с вопросами, 32 000 — с любым одним | invalid |
вопросы ai.decide |
32; вариантов choice — 255; уровней score — от 2 до 10 | invalid; собственные лимиты конструктора вопроса бросают там, где вопрос создаётся |
| сообщение чата | 8000 символов, 5 картинок | ApiError 400 |
| ходы чата | один за раз | ApiError 409 |
| сообщения, которые один человек отправляет в чаты проекта | 100 за 24 ч | limit (429), ничего не сохраняется |
| что модель видит из чата | последние 30 сохранённых сообщений, 5 самых новых картинок | более старые ей не передаются |
что перечисляет ai.messagesResource(id) |
последние 200 сохранённых сообщений | у await chat.messages() на сервере есть все |
| чат без сообщений | удаляется через день после создания | getChat отклоняется с 404 |
- Одна отправка — один запрос вызывающего, сколько бы раундов инструментов она ни заняла; ход чата —
тоже один, как и
ai.decide, сколько бы вопросов он ни задавал. - Дневные сообщения — это сообщения пользователя и ответы отправок без текста (ассистент говорит сам),
и они записываются на устройство, чей вызов сделал отправку. Ход, который не получил ответа, ничего
не оставляет и не считается;
chat.send, за которым нет вызова (таймер), не считается.
Внутри computed: что считается чтением, что отклоняется
Серверный computed выполняется заново всякий раз, когда меняются его
данные, поэтому он только читает. Чат внутри него:
await ai.getChat(id)разрешён: он не читает ничего, за чем следит computed.await chat.messages()отслеживается: сообщение, сохранённое позже, снова прогоняет computed.ai.createChat(),ai.deleteChat(id)иchat.send(…)— записи: прогон падает со статусом 500,computed help.server.ts#helpView: AiChat.insert is a write — a computed only reads (…); write in an endpoint.ai.send— не запись и выполняется, но каждый прогон computed — ещё один платный запрос, при каждом изменении его данных. Спрашивай в эндпоинте и храни ответ в строке, которую читает computed.- Значение computed несёт id чата, но никогда не сам чат: значение, которое держит объект чата,
отклоняется так же, как ответ эндпоинта (500 с подсказкой вернуть
chat.id).
export const conversationView = computed(async (id: number): Promise<{ chat: string, messages: number }> => {
const row = await mine(id) // строка вызывающего: `mine` из chats.server.ts выше
const chat = await ai.getChat(row.chat) // чтение: разрешено, не отслеживается
return { chat: chat.id, messages: (await chat.messages()).length } // отслеживается: новое сообщение прогоняет его снова
})Подводные камни
await ai.send({ model: "claude-…", text }) // ✗ invalid: какая модель отвечает — настройка проекта (Data → AI)
await ai.send({ text }) // ✓
const chat = ai.getChat(id) // ✗ ошибка компиляции: метод чата ждут через await
const chat = await ai.getChat(id) // ✓
await ai.createChat({ system: "You help." }) // ✗ бросает: чат не хранит опций
await chat.send({ ...ASSISTANT, text }) // ✓ кто такой ассистент — при каждой отправке
await chat.send({ text: "" }) // ✗ 400: пустое сообщение
await chat.send({ ...ASSISTANT }) // ✓ без текста: ассистент говорит сам
return await ai.getChat(id) // ✗ эндпоинт: 500 — чат остаётся на сервере
return (await ai.getChat(id)).id // ✓ его id; приложение открывает ai.messagesResource(id)
const messages = ai.messagesResource(id) // ✗ в файле *.server.ts: ошибка компиляции — это метод приложения
const history = await (await ai.getChat(id)).messages() // ✓ так сервер читает чат
const reply = await ai.send({ text }) // ✗ в приложении: ошибка компиляции — ai.send выполняется на сервере
const reply = await ask(text) // ✓ эндпоинт, который вызывает ai.send
ai.send<{ when: Date }>({ text }) // ✗ ошибка компиляции: Date — не JSON
ai.send<{ when: string }>({ text }) // ✓ ISO-дата
ai.send<Report>({ text, tools: { search: ai.webSearch() } }) // ✗ invalid: типизированный ответ не принимает веб-инструмент
const found = await ai.send({ text, tools: { search: ai.webSearch() } })
ai.send<Report>({ text: `${text}\n\nWhat was found:\n${found.text}` }) // ✓ сначала поиск, потом типизированный запрос
ai.send({ system: `Summarize ${url}`, tools: { page: ai.webFetch() } }) // ✗ ссылка только в system: url_not_in_prior_context
ai.send({ system: "Summarize the page the user links.", text: url, tools: { page: ai.webFetch() } }) // ✓ в сообщении пользователя
await ai.decide(text, "Is this spam?") // ✗ invalid: вопрос создают ai.yesNo / ai.choice / ai.score
await ai.decide(text, ai.yesNo("Is this spam?")) // ✓
if ((await ai.decide(text, ai.yesNo("Spam?"))).probability) hide() // ✗ 0.02 — truthy: это вероятность, а не «да»
if ((await ai.decide(text, ai.yesNo("Spam?"))).probability > 0.8) hide() // ✓ свой собственный порог
await ai.decide(order, ai.yesNo("Is it late?")) // ✗ invalid: текст — это строка
await ai.decide(JSON.stringify(order), ai.yesNo("Is it late?")) // ✓
ai.webSearch({ maxUses: 10 }) // ✗ бросает: не больше 5 использований за отправку
tools: { web_search: myTool } // ✗ invalid: web_search / web_fetch — имена веб-инструментов
UIText(reply.text) // ✗ ответ с источниками показан без них
UIColumn(UIText(reply.text), ...(reply.sources ?? []).map((s) => UIText(s.title).onClick(() => openURL(s.url)))) // ✓Смотрите также
- Серверные функции — эндпоинты,
action/resource,RpcError, computed - База данных — строки, которым принадлежит id чата
- Хранимые файлы — параметры
Fileи поляt.image(), картинки, которые несёт запрос - Вход —
db.auth, чей чат чей - Ключи (env) — API другого провайдера, его ключ вне кода