Създаване и управление на колекции
На тази страница
От изолирани файлове към база знания
Досега всеки документ съществуваше самостоятелно: качвахте го, използвахте го за справка и индексът, създаден за случая, изчезваше след заявката. Колекциите променят мащаба: те групират вашите файлове в структурирани бази знания, индексирани веднъж и достъпни за неограничени заявки. Това е основата на RAG (Retrieval-Augmented Generation) с Grok, а разликата личи веднага, когато екипът за поддръжка търси информация в двеста продуктови спецификации вместо в един единствен PDF файл.
Разглеждайте колекцията като умна папка. Вие добавяте документите, xAI ги индексира за семантично търсене, а Grok претърсва тази база, за да отговори с прецизност, извличайки трите най-полезни пасажа сред хилядите налични.
Отделен API и причините за това
Не управлявате колекциите чрез API, който сте използвали от началото на курса. Те попадат в обхвата на Management API, хостван на management-api.x.ai, с основен URL адрес:
https://management-api.x.ai/v1
Това разделение не е архитектурна прищявка. Създаването, модифицирането или изтриването на колекция са административни операции с тежки последствия и xAI изисква отделен ключ за тях: Management API Key с разрешение AddFileToCollection. Ползата за екипите е непосредствена: услугата, която прави заявки към базата от вашето публично приложение, получава стандартния ключ и не може да унищожи нищо; само вашият конвейер за входящи данни (ingestion pipeline) притежава ключа за управление.
Създаване на първата ви колекция
Създаването се свежда до едно единствено извикване с име:
curl -X POST https://management-api.x.ai/v1/collections \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"collection_name": "technical-docs"}'
Отговорът връща идентификатора, който трябва да запазите:
{
"collection_id": "col_xyz789",
"collection_name": "technical-docs",
"created_at": "2026-04-01T10:00:00Z"
}
Изберете това име внимателно: то ще се появява във всички ваши списъци и след шест месеца ще бъде единствената подсказка, позволяваща ви да разграничите две съседни бази. technical-docs изпълнява тази роля; test2 – не. Възприемете конвенция още от първата колекция, защото преименуването на база, вече използвана от три приложения, струва повече, отколкото да я наименувате правилно от самото начало.
Петте налични операции
Management API предоставя пълен набор от CRUD операции за колекциите:
| Операция | Метод | Крайна точка (Endpoint) |
|---|---|---|
| Create | POST | /v1/collections |
| List | GET | /v1/collections |
| Details | GET | /v1/collections/{collection_id} |
| Update | PUT | /v1/collections/{collection_id} |
| Delete | DELETE | /v1/collections/{collection_id} |
Изброяването на вашите колекции става без параметри и осигурява полезна обзорна информация преди всяка операция по поддръжка:
curl https://management-api.x.ai/v1/collections \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Изтриването следва същата логика, като се посочва идентификаторът, получен при създаването:
curl -X DELETE https://management-api.x.ai/v1/collections/col_xyz789 \
-H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
Едно нещо трябва да ви успокои, когато изпълнявате тази команда: изтриването на колекция премахва индексирането, но не и файловете. Вашите документи остават достъпни чрез Files API и могат да бъдат реиндексирани на друго място. Губите структурата за търсене, а не суровия материал – което прави възстановяването на лошо организирана база далеч по-малко рисковано, отколкото изглежда.
Ключови изводи
- Колекциите групират вашите файлове в индексирани бази знания за RAG
- Управлението се извършва чрез Management API (
management-api.x.ai), а не чрез стандартния API - Необходим е Management API Key с разрешение
AddFileToCollection - Лимитите са 100 000 файла и 100 GB на акаунт
- Петте CRUD операции покриват създаване, четене, актуализиране и изтриване