API кескіндерін нормалау бөлек қабат болуы керек

Кескін пішімдерін клиент қалай жіберсе, модельге сол күйінде бере салуға болмайды. URL, base64 бар data URL және идентификаторы бар файл сырттай «міне, кескін» деудің үш тәсілі сияқты көрінеді. Бірақ шлюз үшін бұл үш бөлек міндеттеме: объектіні жүктеу, бинарлық деректерді талдау немесе сақталған ресурсты табу.

API кескіндерін нормалау провайдерді таңдамай тұрып және OpenAI-үйлесімді сұрауды сериализацияламай тұрып орындалуы керек. Сонда қолданба хабарлама бөліктерінің ретін сақтайды, қауіпсіздікті бірізді тексереді және әр жаңа endpoint сайын көбейетін тармақтардың орнына бір келісімшарт алады.

Мұндағы ең жағымсыз қате кескінді өңдеу қатесі ретінде көрінбеуі мүмкін. Пайдаланушы: «Бірінші фотода қаптама, екіншісінде ақау бар. Салыстыр» деп жазады. Сервис кескіндерді мәтіннен бөлек топтап, файл атауы бойынша қайта сұрыптайды да, модельге басқа реттілік жібереді. Модель сенімді жауап береді, бірақ басқа объектілерді талдайды. Журналда екі жарамды кескін мен сәтті жауап қана көрінеді. Сондықтан контент реті интерфейс бөлшегі емес, сұрау деректерінің бөлігі.

Үш пішімнен бір ішкі келісімшарт жақсы

Ішкі келісімшарт кескінді позициясы, көзі және тексерілген метадеректері бар хабарламаның жеке бөлігі ретінде сипаттауы керек. Ол бір API-дегі image_url пішімін қайталамауы тиіс, өйткені басқа endpoint input_image, file_id немесе мүлде бөлек жүктеу тәсілін күтуі мүмкін.

Практикалық келісімшарт мынадай:

type NormalizedImage = {
  kind: "image";
  position: number;
  source: "remote_url" | "inline_bytes" | "managed_file";
  mimeType: "image/jpeg" | "image/png" | "image/webp" | "image/gif";
  bytes?: Uint8Array;
  remoteUrl?: string;
  fileId?: string;
  sha256: string;
  originalName?: string;
  detail?: "low" | "high" | "auto";
};

type NormalizedPart =
  | { kind: "text"; position: number; text: string }
  | NormalizedImage;

type NormalizedMessage = {
  role: "system" | "developer" | "user" | "assistant";
  parts: NormalizedPart[];
};

Мұндағы position массив индексін сән үшін қайталамайды. Ол бөліктер әртүрлі асинхронды операциялардан өткенде қажет. URL жүктеуді, base64 декодтауды, ал file_id метадеректерді оқуды талап етеді. Нәтижелер кез келген ретпен дайын болады. Сондықтан дайын элементтерді кейін жай ғана push() арқылы қоса салуға болмайды.

Келісімшарт шығу тегін ұсынылу түрінен бөледі. Екі кіріс бірдей байттарды қамтуы мүмкін, бірақ біреуі URL-дан, екіншісі base64-тан келген болады. Бұдан кейінгі өңдеу фронтендтің кескінді қалай орағанына емес, маршруттау мен сақтау ережелеріне тәуелді болуы керек.

Ішкі пішім ретінде «әрқашан URL» таңдамаңыз. Inline деректер үшін файлды уақытша бір жерде орналастыруға тура келеді. Жеке файл үшін URL таңдалған модельге жарамсыз болуы мүмкін. Сыртқы URL болса, оны кім жүктей алатынын шешу қажет. Әмбебап жол тез арада әмбебап мәселеге айналады.

Хабарлама бөліктерінің ретін болжаммен қалпына келтіруге болмайды

Рет бастапқы хабарламаны талдаған сәтте қалыптасып, сыртқа жіберілетін payload-қа дейін сақталуы тиіс. Кескіндерді аты, хеші, жүктелу уақыты немесе түрі бойынша сұрыптамаңыз. Сұрауды құру оңай болғаны үшін барлық мәтінді барлық кескіннің алдына да жылжытпаңыз.

Chat Completions жүйесіндегі пайдаланушы мазмұны:

[
  {"type":"text","text":"На первом фото ценник."},
  {"type":"image_url","image_url":{"url":"https://cdn.example.org/price.jpg"}},
  {"type":"text","text":"На втором фото полка. Найди расхождение."},
  {"type":"image_url","image_url":{"url":"data:image/png;base64,iVBORw0KGgo..."}}
]

Нормализатор бірден 0, 1, 2, 3 позициялары бар төрт бөлік жасауы керек. price.jpg файлын жүктеу мен PNG-ді декодтауды қатар бастауға болады, бірақ қорытындыны position бойынша жинау қажет.

const settled = await Promise.all(
  rawParts.map((part, position) => normalizePart(part, position))
);

const parts = settled
  .flat()
  .sort((a, b) => a.position - b.position);

Бұл мысал әдейі қарапайым. Нақты кодта flat() функциясын ережесіз қолданбаңыз: әр кіріс бөлігі дәл бір нормаланған бөлік беруі немесе бүкіл хабарламаға қате қайтаруы керек. Егер функция кейде бір элементті бірнеше элементке бөлсе, қосалқы элементтерге 2.0 және 2.1 сияқты тұрақты позициялар беруі немесе бастапқы бөлік ішінде жеке массив сақтауы қажет. Әйтпесе рет «әдетте дұрыс» болып қалады, ал деректер үшін мұндай қасиет қауіпті.

Шлюз textParts пен imageParts массивтерін бөлек жинап, кейін [...textParts, ...imageParts] құратын оңтайландырудан сақ болыңыз. Бір кескіні бар тестілерде ол зиянсыз көрінеді, бірақ бірнеше қадамнан тұратын визуалды нұсқауларда сұрау мағынасын өзгертеді.

URL-ды сенімсіз желілік кіріс ретінде жүктеңіз

Сыртқы URL клиентке ыңғайлы, бірақ ол сервисіңізді пайдаланушы мақсатын анықтайтын HTTP клиентіне айналдырады. Бұл SSRF-ке, яғни жергілікті сервистерге, ішкі желілерге және бұлттың metadata endpoint-теріне сұрау жіберуге апаратын классикалық жол.

url.startsWith("https://") тексеруі жеткіліксіз. Мекенжай жария доменге апарып, кейін ішкі желіге редирект жасай алады. DNS атауы private IP-ге шешілуі мүмкін. Сервер үлкен файл немесе шексіз редирект қайтара алады.

Жүктеушінің ең аз саясаты мыналарды қамтуы керек:

• Тек https: қабылдау, ал ескі инфрақұрылым үшін қажет болса, арнайы рұқсат етілген http: схемасын бөлек қарастыру.
• URL ішіндегі логин мен құпиясөзді, стандартты емес схемаларды, бос host мәнін және тым ұзын мекенжайларды қабылдамау.
• DNS шешімінен кейін loopback, private, link-local, multicast және қызметтік IP диапазондарын бұғаттау.
• Әр редиректті қайта тексеріп, олардың санына шағын шек қою.
• Қосылу уақытын, оқу уақытын, дене көлемін және рұқсат етілген MIME түрлерін шектеу.

Тек Content-Type тақырыбына сенбеңіз. Сервер HTML құжатын image/jpeg деп атауы, ал прокси 200 кодымен қате бетін қайтаруы мүмкін. Жүктегеннен кейін бинарлық файл сигнатурасын оқыңыз. JPEG FF D8 FF байттарынан басталады, PNG-де тұрақты сегіз байттық сигнатура бар, WebP WEBP маркері бар RIFF контейнерін қолданады. Байтар бойынша MIME анықтайтын кітапхана қолмен жасалған кестеден сенімдірек, бірақ оның нәтижесін де рұқсат етілген тізіммен салыстыру қажет.

URL-дан жүктелген кескінді тұрақты сақтау қоймасына міндетті түрде жазу керек емес. Бір сұрау үшін тексерілген байттарды қысқа өмір сүретін уақытша объектіде ұстауға болады. Қолданба ресурсты қайта пайдаланғысы келсе, басқарылатын файл жасап, иесін, хешін, көлемін және өшіру уақытын жазыңыз.

Base64 алдымен декодтауды, содан кейін тексеруді талап етеді

Base64 кескін пішімі емес. Ол байттарды мәтін түрінде орау тәсілі, сондықтан декодтауға дейін оны кескін деп санауға болмайды. Жол таза base64, data URL немесе үстірт тексеруден кездейсоқ өтетін бұзылған мәтін болуы мүмкін.

Data URL талдауы тақырып пен пайдалы жүктемені тек бірінші үтір бойынша бөлуі керек. Кескін үшін data:<mime>;base64,<payload> пішімін күтіңіз. Өріс атауы image_url болғаны үшін data:text/html;base64,... мәнін үнсіз қабылдамаңыз.

function parseDataUrl(value: string) {
  const comma = value.indexOf(",");
  if (comma < 0) throw new InputError("invalid_image_reference");

  const header = value.slice(0, comma).toLowerCase();
  const payload = value.slice(comma + 1);
  const match = /^data:(image\/(jpeg|png|webp|gif));base64$/.exec(header);

  if (!match || payload.length === 0) {
    throw new InputError("invalid_image_reference");
  }

  if (!/^[a-z0-9+/=\r\n]+$/i.test(payload)) {
    throw new InputError("invalid_image_reference");
  }

  return { declaredMimeType: match[1], payload };
}

Одан кейін байттарды көлем шектеуімен декодтаңыз. Шекті жол ұзындығымен ғана тексермеңіз. Base64 көлемді шамамен үштен біріне арттырады, бірақ бос орындар мен жол ауыстырулар мәтін ұзындығын өзгертеді. Шабуыл декодтаудан кейінгі жадқа бағытталады. Ағындық декодер немесе күтілетін көлемді алдын ала есептеу белгісіз ұзындықтағы жолға Buffer.from() шақырғаннан қауіпсіз.

Содан кейін нақты MIME түрін сигнатура арқылы анықтаңыз. Клиент PNG деп жариялап, байттар JPEG болып шықса, екі дұрыс жол бар: сәйкессіз сұрауды қабылдамау немесе жарияланған түрді нақты түрге ауыстырып, аудит оқиғасын жазу. Құжаттар мен медициналық кескіндер бар жүйелерде қабылдамауды жөн көремін. Сәйкессіздік көбіне кездейсоқ болмайды, ал кейінгі диагностика қымбатқа түседі.

Кескінді себепсіз қайта кодтамаңыз. JPEG-ті қайта сақтау сапасын төмендетіп, пайдалы түс профилін өшіруі және процессор ресурсын жұмсауы мүмкін. Қайта кодтау метадеректерді әдейі жою, қолдау көрсетілмейтін түрді рұқсат етілген түрге айналдыру немесе пиксель өлшемін шектеу қажет болғанда орынды.

Файл жай ғана басқа URL емес, өмірлік циклі бар ресурс

file_id клиентке қысқа сұрау жіберуге және бір байттарды қайта-қайта тасымалдамауға мүмкіндік береді. Бірақ идентификатор файлды кез келген модельге шартсыз тіркеуге болады дегенді білдірмейді. Endpoint file_id қабылдауы, тек URL қолдауы немесе контенттің бөлек формасын талап етуі мүмкін.

OpenAI Responses API құжаттарында кескін input_image элементінде image_url немесе file_id арқылы берілуі мүмкін. Сол жерде файлдар input_file деген бөлек түр ретінде сипатталған. Ескі Chat Completions стилінде контент бөліктерінің құрылымы өзгеше. Мағынасы ұқсас болғанымен, өрістері бірдей емес. Сондықтан адаптерлерді endpoint бойынша бөлек ұстаңыз, шартты операторларды бүкіл қолданбаға таратпаңыз.

Файл сақтау қоймасы кемінде мына төрт сұраққа жауап беруі керек:

1. Объектінің иесі кім және оның ID мәнін көрсетуге кімнің құқығы бар.
2. Жүктеу кезінде қандай байттар мен MIME түрі расталды.
3. Объект қай уақытқа дейін қолжетімді.
4. Қай маршрут оның бастапқы байттарын немесе уақытша сілтемесін ала алады.

file_id мәнін авторизациясыз сұрауға қоспаңыз. Әйтпесе бір tenant пайдаланушысы басқа tenant объектілерінің идентификаторларын болжап немесе алып қоюы мүмкін. UUID болжау ықтималдығын азайтады, бірақ иесін тексерудің орнына жүрмейді.

Екі күйді бөлек ұстау пайдалы. «Жүктелді» дегеніміз байттар сақтау қоймасына жетті деген сөз. «Модельге дайын» дегеніміз MIME түрі, көлем, декодталу мүмкіндігі, қажет болса антивирус ережелері және иесінің саясаты тексерілді деген сөз. Модель тек екінші күйдегі ресурсты көруі керек.

OpenAI Uploads API құжаттары көпбөлікті жүктеуді аяқталғаннан кейін File-ға айналатын аралық объект ретінде сипаттайды. Бұл өз күй моделіңіз үшін жақсы бағдар: бөліктері әлі жиналып жатқан немесе тексеруден өтпеген ресурсты клиентке пайдалануға бермеңіз.

Endpoint адаптері провайдер payload-ын ең соңында құруы керек

Нормаланған объектіні сыртқа сол күйінде шығармаңыз. Соңғы шекарада адаптер нақты маршруттың мүмкіндіктерін таңдап, қажетті пішімді құрады. Мұнда модель мүмкіндіктері кестесі орынды: ол сыртқы URL, data URL және басқарылатын файлдарды қабылдай ма, қандай detail деңгейін түсінеді, маршруттағы ең үлкен көлем қандай.

Responses тәрізді endpoint үшін шығатын мазмұн былай көрінуі мүмкін:

{
  "role": "user",
  "content": [
    {"type":"input_text","text":"Сравни маркировку на двух упаковках."},
    {
      "type":"input_image",
      "image_url":"https://media.example.net/tmp/2f7c.jpg",
      "detail":"high"
    },
    {
      "type":"input_image",
      "file_id":"file_01HXYZ...",
      "detail":"high"
    }
  ]
}

Chat Completions тәрізді endpoint үшін сол мағынаға басқа пішім қажет болуы мүмкін:

{
  "role": "user",
  "content": [
    {"type":"text","text":"Сравни маркировку на двух упаковках."},
    {
      "type":"image_url",
      "image_url":{"url":"https://media.example.net/tmp/2f7c.jpg","detail":"high"}
    },
    {
      "type":"image_url",
      "image_url":{"url":"data:image/jpeg;base64,/9j/4AAQ...","detail":"high"}
    }
  ]
}

Екінші мысал кез келген үйлесімді сервер data URL қабылдайды дегенді білдірмейді. Ол бір JSON-ды «OpenAI пішімі» деп атап, мәселені жабуға болмайтынын көрсетеді. Үйлесімділік әдетте маршрут пен өрістер жиынына қатысты, барлық провайдердің мінез-құлқы толық бірдей дегенді білдірмейді.

Егер модель тек URL қабылдаса, адаптер тексерілген байттарға қолтаңбаланған уақытша сілтеме жасай алады. Маршрут тек inline деректерін қабылдаса, адаптер байттарды base64-қа айналдырады. Екі нұсқа да маршрут ережелеріне сай болмаса, модельге жүгінбей тұрып қате қайтарыңыз. «Провайдер түсініп қалар» деген әрекет қымбат әрі түсіндіруі қиын ақауларға әкеледі.

AI Router-ді дәл осы шекарада қосу орынды: қолданба бір OpenAI-үйлесімді шақыруды сақтайды, ал қолжетімді маршрутты таңдау ережелері бизнес-кодтан тыс қалады. Бұл нормалауды өз тарапыңызда жасауды жоймайды, өйткені бастапқы ретті, файл иесін және пайдаланушы операциясының мағынасын тек қолданба біледі.

Кескінді тексеруде байт, пиксель және құн ескерілуі керек

Файл көлемі шағын болғанымен, пиксельдер тарқатылғаннан кейін өте үлкен болуы мүмкін. Өлшемдері шектен тыс кескін декодтау кезінде көп жад алады, тіпті сығылған PNG зиянсыз көрінсе де. Модельге жібермей тұрып енін, биіктігін, анимациялық пішімдердегі кадр санын және бағытын оқыңыз.

Тексеру жарамдылық пен мақсатқа сәйкестікті бөлуі керек. JPEG техникалық тұрғыдан дұрыс болғанымен, фотода ұсақ мәтінді оқуға пиксель жеткіліксіз болса, нақты тапсырмаға жарамсыз. Шлюз пайдаланушы мақсатын дәлелдеуге міндетті емес, бірақ таңдалған API қолдаса detail мәнін бере алады және нормаланған өлшемдерді аудитке жаза алады.

Расталған байттар бойынша SHA-256 есептеңіз. Бұл хеш:

• бір кескінді қайталап жүктеуді жоюға;
• аналитикада бастапқы URL сақтамай сұрауларды объектімен байланыстыруға;
• ақауды сол ресурста қайта тексеруге;
• әртүрлі file_id мәндерінің бірдей деректерді қамтитынын анықтауға көмектеседі.

Хешті қолжетімділіктің жалғыз құқығы ретінде қолданбаңыз. Белгілі файл үшін хешті болжауға болады және ол өздігінен құпия емес. Хеш мазмұнды сәйкестендіру үшін керек, авторизация үшін емес.

EXIF мәселесін де бөлек шешіңіз. Камера метадеректері координаталарды, түсірілген уақытты және құрылғы моделін қамтуы мүмкін. Егер кескін объектілерді тексеру, сақтандыру немесе медициналық жұмыс қолданбасынан келсе, EXIF-ті әрі қарай жіберу көбіне қажет емес. Оны басқарылатын түрлендіру кезеңінде өшіріңіз, бірақ клиент кескін бағытына сүйенсе, бұл әрекетті үнсіз орындамаңыз. Алдымен бағытты пиксельдерге қолданыңыз, содан кейін тегті жойыңыз.

Қателер клиентке нені түзету керегін көрсетуі тиіс

Провайдердің қателері клиент үшін сирек жақсы келісімшарт болады. Бір сервер unsupported image жазады, екіншісі прокси арқылы HTML қайтарады, үшіншісі file_id мәнін себепсіз қабылдамайды. Нормализатор мәселелерді ертерек ұстап, болжамды кодтардың шектеулі жиынын қайтаруы керек.

Мен мына кодтардан бастар едім:

{
  "error": {
    "code": "unsupported_media_type",
    "message": "JPEG, PNG, WebP және GIF қолдау көрсетіледі.",
    "param": "messages[0].content[3]"
  }
}

invalid_image_reference қате data URL, бос file_id немесе рұқсат етілмеген URL дегенді білдіреді. remote_fetch_denied сілтеменің желілік саясатты бұзғанын көрсетеді. image_too_large байт немесе пиксель лимиті асқанын білдіреді. Егер клиенттің объектінің болғанын білуге құқығы болса, file_not_found пен file_access_denied кодтарын біріктірмеңіз. Сыртқы клиент үшін бірдей жауап қайтарып, нақты себепті аудитте қалдырған қауіпсіз.

Журналда request ID, tenant ID, элемент позициясы, дерек көзі түрі, жарияланған және нақты MIME түрі, көлемі, хеші және таңдалған маршруты сақталсын. Base64-ты журналға жазбаңыз. Токендері бар толық уақытша URL мекенжайларын да қалдырмаңыз. Журнал өңдеу тізбегін қалпына келтіруге көмектесуі керек, кескіндердің екінші қорғалмаған қоймасына айналмауы тиіс.

Тек сәтті JPEG-ті емес, пішімдер арасындағы ауысуды тестілеңіз

Жария JPEG бар бір тест ештеңені дерлік тексермейді. URL-дан data URL-ға, file_id-ден уақытша URL-ға, base64-тан басқарылатын файлға ауысуларды және әр кезеңдегі қабылдамауларды қамтитын матрица керек.

Ең аз тест жиынына екі кескіннің арасында мәтіні бар хабарлама, тыйым салынған желіге апаратын редиректі URL, жалған MIME түрі бар data URL, басқа tenant-ке тиесілі файл және пиксель өлшемі саясатқа сыймайтын кескін кіруі керек. Әр жағдайда жауап кодын ғана емес, жергілікті қате болғанда провайдерге қоңырау шалынбағанын да тексеріңіз.

Бәсекелестікке арналған тест қосыңыз. Бірінші кескін баяу жүктеліп, екіншісі бірден декодталсын. Соңғы массив бастапқы ретте қалуы керек. Дәл осы тест нәтижені операциялардың аяқталу уақыты бойынша жинау азғыруын ұстайды.

Жақсы түрлендіру қабаты модельді ақылды етпейді. Ол модель пайдаланушы көрсеткен дәл сол объектілерді, сол ретпен және сол қолжетімділік шекараларымен көретініне кепілдік береді. Мультимодальды қолданба үшін бұл қосымша сантехника емес, жауаптың дұрыстығының бір бөлігі.