ИИ: языковая модель (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") — см. Тестирование ИИ на своей машине.

Обзор

TypeScript
// 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
}
TypeScript
// 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 run ai.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. Флоу может проверить отказ:

JSON
{ "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.

TypeScript
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, и его варианты можно собрать во время выполнения — собственные теги человека, — чего тип выразить не может.

TypeScript
// 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: ответ проверен по типу
}
TypeScript
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 КБ:

TypeScript
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, который эндпоинт получил от приложения, или хранимый файл, прочитанный из базы данных.

TypeScript
// 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)
}
TypeScript
// 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 картинок на запрос — с messages 5 на все сообщения вместе.
  • Модель видит каждую как JPEG, повёрнутый так, как задумала камера (HEIC-фото читаются), не больше 1568 px по длинной стороне. Вместе, в таком виде, они занимают не больше 6 МБ: больше — invalid, отправь меньше.
  • С картинками text можно опустить.
  • Картинки — это вход: они учитываются в usage.input.

Целый разговор для модели: messages

Чтобы дать модели разговор вместо одного текста — тот, что хранит твой сервер, или историю чата, прочитанную для пересказа, — передай messages; ответ — следующее сообщение модели.

TypeScript
type AiMessage =
  | { role: "user", text?: string, images?: AiImage[] }       // текст, картинки или оба
  | { role: "assistant", text: string, calls?: AiToolCall[] } // что модель сказала раньше и какие вызовы сделала
TypeScript
// 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).

TypeScript
// 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 })
}
TypeScript
// 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()

Сообщение человека появляется, когда сервер его сохранил, под ним — ответ, пока модель его пишет, и этот ответ остаётся одним сохранённым сообщением. Сторона сервера:

TypeScript
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, вызов отдельной инструкцией или промис, отложенный на потом, валят компиляцию:

    TypeScript
    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.

TypeScript
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, когда сервер отказывает: 404 No 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:
TypeScript
// 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, 404 No such chat.

Модель вызывает твой код: инструменты, ai.tool (function calling)

Чтобы модель могла что-то найти или сделать, пока отвечает, — найти заказ, проверить остатки, сохранить результат, — дай ей инструменты: функции твоего сервера, у каждой описание и типизированный параметр. Модель вызывает их, читает, что они вернули, и отвечает, когда у неё есть всё нужное.

TypeScript
// 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 }
}
TypeScript
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). Его вызов заканчивает ход ассистента, приложение показывает его аргументы, а следующее сообщение человека — ответ на него.

TypeScript
// 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 })              // ответ на ждущий вопрос: для модели — его результат
}
TypeScript
// 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). Верни разговор с ответом человека после него — и снова инструмент:
TypeScript
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 на своих серверах: ни функции, ни описания, только инструмент под тем именем, которым его называет твоё приложение.

TypeScript
// 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 ?? [] }       // показывай источники вместе с ответом
}
TypeScript
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.
TypeScript
// 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.

TypeScript
// 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"
  })
}
TypeScript
// классификация текста: вердикт с вероятностями, ~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:
TypeScript
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             // не решено: показан, как раньше
TypeScript
// 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.

TypeScript
class AiError extends Error { readonly code: AiErrorCode }   // сервер: что бросают ai.send и chat.send
err.ai?: AiErrorCode                                         // приложение: у RpcError — и у Failure в action / resource
code почему вызов приложения, если не поймать
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 и говори человеческими словами:

TypeScript
// 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()

На сервере лови его там, где ответ необязателен:

TypeScript
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).
TypeScript
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 }   // отслеживается: новое сообщение прогоняет его снова
})

Подводные камни

TypeScript
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))))   // ✓

Смотрите также