Automatizovaný příjem souborů přes Azure File Share
Tento postup použijte, pokud schválené dokumenty vznikají na lokálním nebo on-premises souborovém serveru a mají se automaticky přenášet do Siesta AI. Synchronizační služba publikuje řízenou kopii do Azure File Share. Siesta AI potom tento share načte do kolekce dat pro agenta.
Jde o integrační vzor, ne o nové API. Přesné propojení metadat s dokumenty je nutné ověřit pilotem proti nasazené ingestion službě.
Architektura
+---------------------+
| Interní share |
| Zdroj pravdy |
+----------+----------+
|
v
+---------------------+
| Synchronizační |
| služba a filtry |
+----------+----------+
|
v
+---------------------+
| Azure File Share |
| Landing zone |
+----------+----------+
|
v
+---------------------+
| Siesta AI |
| Kolekce dat |
+----------+----------+
|
v
+---------------------+
| Agent |
| Odpovědi a zdroje |
+---------------------+
Synchronizační služba a Siesta AI používají dva oddělené přístupy:
- Synchronizační identita zapisuje schválené soubory a metadata do Azure File Share.
- Connection v Siesta AI čte stejný share pro ingestion.
Nedávejte Siesta AI právo zápisu jen proto, že ho potřebuje uploader. Přihlašovací údaje uploaderu nepatří do polí Data source v Siesta AI.
Odpovědnosti
| Role | Odpovědnost |
|---|---|
| Vlastník dokumentů | Schvaluje složky, typy souborů, výjimky, stavové hodnoty, retenci a způsob odstranění |
| Azure administrátor | Vytváří Storage Account a share, nastavuje síť, identity-based SMB přístup, RBAC, ACL, logování a rotaci přístupů |
| Provozovatel synchronizace | Provozuje důvěryhodnou synchronizační službu, aplikuje filtry, publikuje soubory a metadata atomicky a sleduje chyby přenosu |
| Siesta AI administrátor | Vytváří Connection, kolekci a Azure File Share source, nastavuje přístup a frekvenci a ověřuje ingestion |
| Vlastník agenta | Přiřazuje kolekci, určuje práci s citacemi a chybějící odpovědí, spouští testy a sleduje kvalitu |
Jedna osoba může zastávat více rolí, ale každá odpovědnost musí mít určeného vlastníka a náhradníka.
Fáze 1: Příprava Azure landing zone
- Vytvořte nebo vyberte Azure Storage Account s podporou Azure Files.
- Vytvořte samostatný file share pro danou ingestion hranici.
- Zvolte stabilní název, například
approved-documents. - Omezte síťový přístup na důvěryhodný synchronizační server a schválenou ingestion cestu Siesta AI.
- Zapněte diagnostické logování Azure a nastavte retenci.
- Definujte samostatnou identitu uploaderu a čtečky.
Upřednostněte identity-based SMB autentizaci. Synchronizační identitě přidělte roli Storage File Data SMB Share Contributor v nejužším praktickém rozsahu a odpovídající ACL pro soubory a adresáře. Role povoluje přístup na úrovni share, ACL řídí přístup uvnitř share. Použijte návod Microsoftu pro oprávnění Azure Files na úrovni share.
Čtečka Siesta AI má dostat pouze přístup vyžadovaný nasazeným typem Connection. Pokud současná integrace používá connection string Storage Accountu, považujte jej za široce oprávněný secret, ukládejte jej pouze v Connections, pravidelně jej rotujte a nikdy jej nekopírujte do popisu nebo selektoru zdroje.
Fáze 2: Připojení share na důvěryhodném Windows serveru
Synchronizaci provozujte na spravovaném serveru, který vidí interní úložiště a může komunikovat s Azure Files. SMB přístup k Azure Files vyžaduje odchozí TCP port 445. Nejdříve ověřte síťovou cestu, teprve potom řešte přihlašovací údaje.
Připojení pomocí Azure Portal
- Přihlaste se do Azure Portal.
- Otevřete Storage accounts, vyberte cílový účet a otevřete Data storage > File shares.
- Vyberte ingestion share a klikněte na Connect.
- Vyberte Windows, písmeno disku, například
Z:, a schválený způsob autentizace. - Zkopírujte vygenerovaný PowerShell příkaz.
- Na důvěryhodném serveru spusťte PowerShell jako administrátor a příkaz proveďte.
- V Průzkumníku souborů ověřte dostupnost share a otestujte, že synchronizační identita dokáže ve schválené složce vytvořit, nahradit a odstranit testovací soubor.
Aktuální požadavky a příkazy najdete v návodu Microsoftu pro připojení Azure Files ve Windows.
Nezaměňujte tyto hodnoty
| Hodnota | Příklad | Kde se používá |
|---|---|---|
| Název Azure File Share | approved-documents | Pole File Shares v Data source Siesta AI |
| UNC cesta | \\\\storageaccount.file.core.windows.net\\approved-documents | SMB přístup a příkazy pro připojení ve Windows |
| Namapovaný disk | Z:\\ | Lokální cesta dostupná jen na serveru, kde je share připojen |
| Interní zdrojová cesta | \\\\fileserver\\departments\\manuals | Upstream cesta čtená synchronizační službou |
Do pole File Shares v Siesta AI zadejte pouze přesný název share. Nezadávejte Z:\\, UNC cestu, podsložku ani URL Blob Storage.
Fallback pomocí klíče Storage Accountu
Klíč Storage Accountu lze použít, pokud identity-based SMB není dostupné, jde však o méně bezpečný fallback. Klíč poskytuje široký přístup jako identita Storage Accountu, obchází individuální autorizaci uživatele a musí být chráněn a rotován. RBAC uživatele nepovažujte za účinný pro SMB přístup, pokud se mount autentizuje klíčem účtu.
Fáze 3: Výběr a synchronizace souborů
Synchronizační služba musí publikovat řízenou sadu dat, ne kopii všeho, k čemu má server přístup.
Pravidla výběru
- Povolte pouze schválené kořenové složky a typy souborů.
- Vynechte drafty, dočasné soubory, archivy, obsolete složky, zálohy a nepodporované formáty.
- Odmítněte obsah mimo schválenou cílovou skupinu nebo úroveň důvěrnosti.
- Při aktualizacích zachovejte stabilní relativní cesty nebo stabilní ID dokumentů.
- Aktualizujte existující dokument, nevytvářejte při každém běhu duplicitní kopii.
- Určete, zda se upstream soubor po odstranění smaže, označí jako deprecated, nebo zůstane po definovanou dobu.
- Zapisujte provozní log s ID běhu, časem začátku a konce, počty, objemem dat, vynechanými položkami, odstraněními a chybami. Nelogujte secrets ani obsah dokumentů.
Začněte whitelistem, například:
Schválené kořeny: \\fileserver\departments\manuals\approved
Typy souborů: .pdf, .docx, .xlsx, .pptx, .md, .txt
Vynechané názvy: ~$*, *.tmp, *.bak
Vynechané cesty: drafts, archive, obsolete, temp
Atomické publikování
Siesta AI nesmí načíst neúplnou dávku. Každý soubor nahrajte pod dočasným názvem nebo do staging cesty, ověřte velikost nebo checksum a teprve potom jej atomicky přejmenujte či přesuňte na cílovou cestu. Hotový metadata manifest publikujte až po dokončení všech dokumentů v dávce.
Pokud zvolená implementace neumí atomický rename, publikujte do verzované staging složky a ověřenou release hranici přepněte až po validaci.
Metadata kontrakt
Kanonickým formátem je JSON, protože formulář Azure File Share nabízí JSON Metadata Definitions. CSV může existovat jako upstream formát, ale synchronizační proces jej musí převést na podporovaný JSON kontrakt, pokud nasazení výslovně nepodporuje CSV.
Následující sidecar manifest je integrační kontrakt. V pilotu potvrďte, jak nasazená ingestion služba manifest objeví, propojí záznamy se soubory nebo chunky, ověří neznámá pole a zpracuje chybějící záznamy.
{
"schema_version": "1.0",
"generated_at": "2026-07-21T08:30:00Z",
"documents": [
{
"document_id": "operations-boiler-startup-v3",
"file_path": "manuals/operations/boiler-startup.pdf",
"source_path": "\\\\fileserver\\operations\\approved\\boiler-startup.pdf",
"title": "Boiler Startup Procedure",
"category": "Operations",
"owner": "Operations Engineering",
"version": "3.0",
"status": "approved",
"last_modified": "2026-07-20T14:05:31Z",
"confidentiality": "internal",
"tags": ["boiler", "startup", "safety"]
}
]
}
Definice polí
| Pole | Požadavek |
|---|---|
document_id | Povinný, stabilní a jedinečný identifikátor. Při nové verzi stejného logického dokumentu se nemění. Neodvozujte jej z dočasného názvu souboru. |
file_path | Povinná cesta relativní ke kořeni Azure File Share se separátory /. Musí ukazovat právě na jeden publikovaný soubor. |
source_path | Původní interní cesta pro audit a řešení problémů. Nezobrazujte ji v citacích pro uživatele bez schválení. |
title | Čitelný název dokumentu pro kontrolu a, pokud je podporováno, citace. |
category | Řízená business kategorie, ne nahodilý výpis složek. |
owner | Tým nebo role odpovědná za správnost obsahu. Upřednostněte trvalý název skupiny před osobním e-mailem. |
version | Verze ze zdrojového systému. Používejte jednotnou konvenci. |
status | Stav životního cyklu. Doporučené hodnoty: approved, deprecated, archived, draft. Ingestovat se mají pouze výslovně schválené hodnoty. |
last_modified | Čas změny ve zdroji ve formátu RFC 3339 včetně časové zóny, například 2026-07-20T14:05:31Z. |
confidentiality | Řízená klasifikace, například public, internal, confidential nebo hodnota schválená organizací. |
tags | JSON pole normalizovaných štítků pro vyhledávání a governance. Používejte stabilní výrazy bez duplicit lišících se jen velikostí písmen. |
Manifest před publikováním validujte. Odmítněte duplicitní document_id, chybějící soubory, absolutní file_path, neplatné časové údaje, nepodporované stavy a klasifikace, které neodpovídají cílové kolekci.
Fáze 4: Konfigurace Siesta AI
- Požádejte administrátora o vytvoření Azure Storage Account Connection se čtecím přístupem do landing zone.
- Vytvořte kolekci s business názvem, vlastníkem, cílovou skupinou a retenčním pravidlem.
- Přidejte Data source typu Azure File Share.
- Vyberte připravenou Connection.
- Do File Shares zadejte přesný název Azure File Share.
- Pro pilot zvolte frekvenci On Demand.
- JSON Metadata Definitions nastavujte pouze podle kontraktu nasazené ingestion služby.
- Spusťte ingestion a zkontrolujte Files, chunky, stav a Logs.
- Kolekci nejprve přiřaďte testovacímu agentovi.
Lokální aplikace a backend Siesta AI potvrzují, že JSON Metadata Definitions předávají při vytvoření Azure File Share source. Samy však nedokazují, jak externí RAG služba propojí sidecar manifest s každým chunkem. Dokud to neprokáže pilot, považujte toto chování za neověřené.
Fáze 5: Pilot, monitoring a produkční provoz
V izolované kolekci proveďte tyto testy:
| Test | Očekávaný výsledek |
|---|---|
| Nový schválený soubor | Objeví se jeden čitelný a indexovaný dokument se správným názvem a zdrojem |
Aktualizace se stejným document_id | Nový obsah nahradí nebo verzovaně aktualizuje logický dokument bez nechtěné duplicity |
| Draft nebo vynechaná cesta | Soubor se přeskočí a objeví se v logu synchronizace |
| Odstraněný zdrojový soubor | Použije se popsané pravidlo delete, deprecate nebo retain |
| Chybně vytvořená metadata | Dávka nebo záznam bezpečně selže s užitečnou chybou bez secrets |
| Prázdný share | Běh skončí bezpečně a nesmaže platný produkční obsah, pokud to není výslovně navrženo |
| Otázka se známou odpovědí | Agent odpoví z kolekce a cituje dohledatelný dokument |
| Otázka bez odpovědi | Agent uvede, že odpověď v kolekci není, a nehádá |
| Nová verze zdroje | Po synchronizaci agent použije novou schválenou verzi |
Před produkcí zaznamenejte výchozí počet dokumentů, počet vynechaných položek, poslední úspěšný běh, očekávaný harmonogram, vlastníky, příjemce alertů, obnovovací postup, rotaci přístupů a pravidla mazání.
Sledujte obě části pipeline:
- Synchronizační služba: chyby skenování, odmítnuté soubory, chyby přenosu, validace manifestu, délka běhu a poslední úspěšné publikování.
- Siesta AI: stav zdroje, poslední a další sync, Indexed/Readable soubory, chyby zpracování, kvalita retrievalu, citace a přístupové či auditní události.
Kolekci pozastavte nebo odpojte, pokud landing zone obsahuje neschválená data, metadata neodpovídají souborům, odstranění způsobí nebezpečné odpovědi nebo agent cituje zastaralou verzi.