Skip to main content

Knowledge graphs: build a version

Build a version of a knowledge graph from one PDF, for a new graph or an existing one; read it before your first build and when a build is slow, cancelled or fails.

Before you start: one PDF of up to 32 pages and 50.0 MB, and no other version of the graph building.

Steps​

Start the build​

  1. New graph: in Knowledge Graphs click Create knowledge graph. The form Create a knowledge graph asks for Name (required, up to 100 characters) and Description (up to 500; "What this graph covers, for the catalogue and the agent editor"). Existing graph: click New version on the graph's page, its Versions section or its list row; the form New version of Name has no name fields.
  2. Under Source PDF ("One PDF of up to 32 pages and at most 50.0 MB.") click Choose PDF. The label reads Checking PDF… while Studio counts the pages in your browser, then shows report.pdf (<size>, <pages> pages) and Choose a different PDF.
  3. Click Create and build v1 (or Start build). The label runs Creating graph…, Starting build…, Uploading PDF…, then the build rail opens. Do not close the tab while uploading; the browser warns "Your PDF is still uploading." Afterwards you can leave; the build continues on the server.

A disabled button explains itself on hover ("Choose a PDF first.", "Give the knowledge graph a name.", "Finish or cancel the pending upload first."). Studio refuses a file, in red under the picker, with "Only PDF files are supported.", "Knowledge graphs accept PDFs of 50.0 MB or less.", "Knowledge graphs accept PDFs of 32 pages or fewer." (also the service's failure reason for an over-long document) or "Could not read PDF".

Follow the build​

  1. The screen Building v2 of Name notes "You can leave this page" and, for a pulled version, Imported from <deployment> · v3 of Name. After "Reading build progress…" the six-step rail appears: Upload, Prepare document, Parse document, Build graph, Import graph, Train embeddings, each with an icon (waiting, running, complete, failed or cancelled) and started 10:15 or finished 10:21; a failed step shows its error.
  2. Progress refreshes every 5 seconds while the tab is visible. Elsewhere the build reads Build graph, step 4 of 6 in the Versions table and under the graph's meta line. Return any time with View build log on the version's row.
  3. The Live log streams the service's log: the header shows Connecting…, Live, Reconnecting…, Unavailable or Ended and a line count; click it to fold; scroll up to pause and Latest to resume; Copy takes every buffered line (the last 500). It ends with "Log stream ended." plus any failure reason.

Cancel, fail, retry​

  1. Cancel build (footer, the version's row, or beside the graph's status line) asks Stop building v2?: the build stops at its next checkpoint, usually within a few minutes, and the partial graph is removed. Stop build or Keep building. The version then reads Cancelled.
  2. A failed build marks its step and reads Failed: "v2 failed at Build graph: reason. Retry as a new version or delete it." The reason also sits under the Failed badge in the table. Other versions are unaffected.
  3. Retry as new version (footer or row) rebuilds the stored document as a fresh version. If the document expired you return to the form with "The stored document is no longer available"; choose the PDF again. Retry is disabled while another version builds.
  4. Delete version in the footer asks Delete v2? ("This cannot be undone.") with Delete version or Keep it, then opens the graph's page.

If the upload fails​

The form shows Upload failed: HTTP 5xx with Retry upload (the same file) and Cancel v2 (cancels the version). The picker is disabled meanwhile. "Could not cancel the pending version.": try again from the Versions table. An upload not completed within 15 minutes fails the version: its row reads Failed, reason UPLOAD_NOT_COMPLETED, and the partial upload is removed; click New version and choose the PDF again.

What you should see​

While building: the Live log reading Live, a Building badge with the step in the Versions table, and New version and Delete graph disabled. At the end: "v2 is ready. Agents can pin to it now.", a stats line such as 650 nodes · 1,240 edges · 6 relation types · 32 pages, Open graph, and the version offered in the agent Configure dialog as v2 · Ready · <date>.

Notes​

RuleValue
Documents per versionone PDF, up to 32 pages and 50.0 MB
Upload window15 minutes; then the version reads Failed, UPLOAD_NOT_COMPLETED
Build timedepends on the document and the deployment's sizing; a 26-page document takes hours on the xs tier
  • The build cannot start: "This graph already has a version building", "Studio is updating" (wait a few minutes), "Studio is temporarily unavailable", "We couldn't reach the knowledge graph service." or "The build could not be started (HTTP 5xx)." "v2 was created but the service returned no upload URL.": cancel it from the Versions table and start again.
  • The rail reads "Studio is temporarily unavailable": Studio keeps reading every 5 seconds. Live log reads Unavailable: the stream was refused; the rail still shows progress.
  • Pin agents to the new version in Configure, or move them all with Move N agents here.