Sumber workspace
Sebuah workspace (id yang sama dengan sesi chat-nya) menyimpan kumpulan sumber, dan setiap pertanyaan di dalamnya dijawab dari kumpulan itu. Rute ini membaca, menyimpan, serta menambah atau menghapus satu berkas sekaligus.
Semua rute memerlukan header API key yang dikonfigurasi dan header principal tepercaya (X-User-Subject, plus klaim role/unit/level opsional) seperti rute lain yang membawa principal; lihat Percakapan dan memori. Pemanggil yang bukan anggota workspace mendapat 404 di setiap rute di bawah, jawaban yang sama dengan id workspace yang tidak dikenal. Anggota dengan role viewer boleh membaca kumpulan sumber dan mendapat 403 pada setiap penulisan. Tiga role workspace dan izin masing-masing tercantum di anggota workspace.
Id dokumen adalah UUID documents.id milik AI engine — aiDocumentId dari event status Kafka, document_id pada hasil search atau sitasi, atau id dari GET /workspaces/{id}/documents. Bukan documentId milik registri partner. Rute penulisan pemilihan sources menolak id dokumen yang tidak valid dengan 422; penghapusan unggahan menggunakan kontrak terpisah di bawah.
Penyimpanan sources, pemilihan per berkas, dan pemilihan otomatis saat ingesti memeriksa ulang keberadaan baris dokumen yang diminta di bawah row lock workspace. Dokumen yang dihapus sebelum lock diperoleh tidak disimpan dalam pilihan, meskipun ditemukan pada pencarian awal. Respons berisi kumpulan yang telah diresolusikan.
GET /workspaces/{workspace_id}/sources
Mengembalikan kumpulan tersimpan, diresolusikan terhadap korpus saat ini. Semua anggota, termasuk viewer, boleh memanggilnya.
| Field | Tipe | Makna |
|---|---|---|
whole_corpus | boolean | Semua dokumen yang boleh dibaca pemanggil. |
collection_ids | array string | Koleksi utuh, masing-masing dihitung satu sumber. |
document_ids | array string | Dokumen yang dipilih satu per satu. |
excluded_document_ids | array string | Dokumen yang dikeluarkan dari kumpulan. Pengecualian menang atas pemilihan. |
source_count | integer | Koleksi + dokumen + 1 bila whole_corpus. |
answerable | boolean | false bila kumpulan kosong; workspace lalu menolak menjawab alih-alih melebarkan ke seluruh korpus. |
kept_own_uploads | integer | Selalu 0 pada pembacaan. Hanya penyimpanan yang melaporkannya. |
issues | array | Pilihan yang berpindah (kind: "moved", dengan current_document_id) atau hilang (kind: "missing"). Tidak pernah dibuang diam-diam. |
PUT /workspaces/{workspace_id}/sources
Menyimpan kumpulan sumber. Hanya owner dan partner; viewer mendapat 403.
{
"whole_corpus": false,
"collection_ids": ["JDIH"],
"documents": [{"document_id": "0f2b0000-0000-4000-8000-000000000001"}],
"excluded_document_ids": []
}
Field extra ditolak dengan 422, begitu pula id dokumen yang tidak valid di documents atau excluded_document_ids. Per dokumen hanya document_id yang diterima; kunci konten stabil yang membuat pilihan bertahan saat ingest ulang dibaca dari baris kami sendiri.
Apa yang diganti oleh penyimpanan. Koleksi, whole_corpus, dan dokumen korpus bersama diganti persis dengan apa yang disebut request. Menghapus centang satu item akan menghapusnya.
Apa yang dipertahankan oleh penyimpanan. Unggahan milik workspace yang sudah dipilih dan tidak disebut dalam request tetap dipilih. Penyimpanan yang tidak menyebut sebuah berkas bukan keputusan untuk menghapusnya, dan produksi kehilangan sepuluh unggahan karena hal itu. Hanya unggahan terindeks yang belum digantikan versi baru yang dipertahankan. Pilihan yang sama tetap dipertahankan saat menyimpan whole_corpus: true, sehingga mengaktifkan lalu menonaktifkan mode seluruh korpus tidak menghapusnya. source_count menghitung pilihan tersimpan tersebut bersama entri seluruh korpus.
kept_own_uploads pada response dan pada baris audit (origin: "workspace-sources", change: "save") melaporkan berapa banyak yang dipertahankan. Klien yang mengirim kumpulan basi karena itu melihat jumlahnya, bukan menemukan celahnya belakangan.
Menghapus satu berkas. Unggahan sendiri yang tidak disebut dalam documents tetap dipilih. Menyebutnya dalam excluded_document_ids sengaja menghapusnya: pengecualian menang atas pemilihan, dan penyimpanan berikutnya yang tidak menyebut berkas itu tidak mengembalikannya setelah berkas tidak lagi dipilih. PUT mengganti pengecualian; ulangi pengecualian yang diperlukan untuk lingkup koleksi atau seluruh korpus. DELETE per berkas di bawah juga mencatat penghapusan agar bertahan pada penyimpanan berikutnya, termasuk seluruh korpus. Menyebut berkas di documents menghapus catatan tersebut; pengecualian eksplisit dalam request yang sama tetap menang.
POST /workspaces/{workspace_id}/sources/documents
Menambahkan satu dokumen ke kumpulan. Hanya owner dan partner; viewer mendapat 403. Dokumen yang tidak dapat dilihat pemanggil, atau id yang tidak dikenal, mendapat 404.
{"document_id": "0f2b0000-0000-4000-8000-000000000001"}
Bersifat menambah: kumpulan tersimpan dibaca lalu ditulis kembali dengan berkas ini ditambahkan, di dalam satu kunci baris, sehingga dua toggle tidak saling menghilangkan dan aksi per berkas tidak mungkin mengosongkan sisa kumpulan. Memilih berkas yang pernah dihapus menghapus catatan penghapusannya. Idempoten — memilih berkas yang sudah dipilih mengembalikan kumpulan yang sama. Mengembalikan kumpulan yang telah diresolusikan.
DELETE /workspaces/{workspace_id}/sources/documents/{document_id}
Menghapus satu dokumen dari kumpulan dan mencatat keputusan itu, yang membuat penyimpanan berikutnya tidak memasukkannya kembali. Hanya owner dan partner; viewer mendapat 403. Dokumen yang tidak dapat dilihat pemanggil, atau id yang tidak dikenal, mendapat 404.
Dokumen dikeluarkan dari document_ids dan ditambahkan ke excluded_document_ids; mode seluruh korpus dapat tetap menyimpan pilihan per dokumen, tetapi pengecualian juga mengeluarkan berkas itu dari lingkup seluruh korpus. Idempoten. Mengembalikan kumpulan yang telah diresolusikan.
DELETE /workspaces/{workspace_id}/documents/{document_id}
Menghapus satu unggahan yang dimiliki workspace, secara permanen: baris indeksnya, chunk-nya, dan objek mentahnya. Hanya owner dan partner; viewer mendapat 403. Berhasil mengembalikan 204 tanpa isi.
Rute mencatat penghapusan dari sources sebelum menghapus dokumen. Setelah pembaruan sources berhasil, kegagalan sebelum penghapusan index membiarkan berkas tetap terindeks dan tidak dipilih, termasuk melalui lingkup koleksi dan seluruh korpus. Setelah index dihapus, catatan penghapusan dari sources dibersihkan. Pilihan notebook yang masih merujuk dokumen terhapus terbaca missing di issues.
500 generik berarti hasilnya belum pasti: pembaruan sources atau audit dapat gagal sebelum atau setelah penghapusan index. Baca GET /workspaces/{workspace_id}/sources dan GET /workspaces/{workspace_id}/documents, lalu coba ulang hanya jika dokumen masih tercantum.
| Status | Detail | Kapan |
|---|---|---|
204 | Isi kosong | Terhapus. |
403 | { "detail": "..." } | Pemanggil adalah viewer. Tidak ada yang berubah. |
404 | { "detail": "Document not found" } | Bukan dokumen yang dimiliki workspace ini: berkas workspace lain, dokumen korpus bersama, versi yang digantikan, atau id yang tidak dikenal. Tidak ada yang berubah. |
409 | { "detail": "This upload is still being processed. Delete it after it finishes." } | Unggahan tujuan berstatus queued, processing, atau retrying, baris dokumen berstatus pending atau processing, atau unggahan aktif di workspace belum memiliki id dokumen tersimpan. Tidak ada yang dibatalkan dan tidak ada yang berubah. Coba lagi setelah selesai. |
500 | { "detail": "Document removed from the index but its raw object could not be deleted" } | Baris indeks sudah terhapus dan penghapusan objek mentah gagal. Jangan dicoba ulang: percobaan ulang mengembalikan 404. Laporkan objek yatim ke operator. |
Setiap unggahan berstatus queued, processing, atau retrying di workspace ini yang belum memiliki id dokumen tersimpan memblokir semua penghapusan dokumen dengan 409, termasuk dokumen lain, sampai unggahan tersebut selesai.
Setelah pemeriksaan unggahan aktif lolos, id yang tidak valid mengembalikan 404. Id unggahan (doc-…) dapat mengidentifikasi unggahan aktif untuk 409; gunakan UUID dokumen tersimpan untuk menghapus unggahan yang sudah selesai.
Unggah ulang berkas
Status pemilihan mengikuti dokumennya, bukan unggahannya.
- Unggah ulang berkas yang identik byte dengan versi sumber yang sama mengembalikan baris dokumen yang sudah ada sebelum pemilihan dijalankan. Status pemilihan, termasuk catatan penghapusan, tetap dipertahankan. Pilih kembali melalui
POST …/sources/documentsuntuk memulihkannya. - Versi baru yang diunggah melalui
POST /workspaces/{id}/documents/{document_id}/replacedipilih otomatis ketika terindeks dan lolos gerbang review OCR, menggantikan pendahulunya didocument_ids. Versi baru tetap dipilih meskipun versi lama telah dibatalkan pilihannya; catatan penghapusan versi lama tetap terikat pada id lamanya. Jika versi lama dipilih, versi itu tetap menjawab sampai versi baru siap. - Berkas berbeda dipilih otomatis setelah terindeks dan lolos review OCR, tanpa menghapus catatan penghapusan berkas lain.
Migrasi toggle per berkas di Studio
Toggle yang dibangun di atas PUT /sources mewarisi cara gagalnya: satu payload basi mengosongkan kumpulan. Pindahkan setiap kontrol per berkas ke panggilan aditif.
| Aksi | Sebelum | Sesudah |
|---|---|---|
| Centang satu berkas | Kirim ulang seluruh kumpulan dengan berkas ditambahkan | POST …/sources/documents dengan {"document_id"} |
| Hapus centang satu berkas | Kirim ulang seluruh kumpulan dengan berkas dihapus | DELETE …/sources/documents/{document_id} |
| Centang atau hapus centang satu koleksi | Kirim ulang seluruh kumpulan | tidak berubah — PUT …/sources |
| Simpan seluruh panel Sumber | PUT …/sources | tidak berubah, dan unggahan sendiri yang tidak disebut kini dipertahankan; baca kept_own_uploads |
| Tampilkan status pemilihan | Gabungkan GET …/sources dengan daftar berkas | tidak berubah |
Kedua rute per berkas mengembalikan kumpulan yang telah diresolusikan, jadi klien merender ulang dari response dan tidak pernah menggabungkan secara lokal.
Berkas yang dihapus pengguna sebelum perubahan ini tercatat sebagai kelalaian, bukan penghapusan, dan jaring pengaman hanya mempertahankan berkas yang masih dipilih. Berkas yang sudah terlepas tetap terlepas; pilih kembali dengan POST …/sources/documents untuk mengembalikannya.