Before Kimi Answers, Check Your Files API Extraction

A document upload succeeds. The content endpoint returns readable Markdown. Kimi then answers a question about the document. These are three separate events, and only the last involves answering your question. If a table lost its header during extraction, a confident answer can simply be a fluent interpretation of incomplete evidence.

This ingestion notebook examines the handoff between Kimi Files content extraction and a model request. Its subject is the representation that reaches the model: which row a value belongs to, whether its unit survives, and whether a reviewer can trace the answer back to the exact extracted material. Every table and response fixture below is synthetic. No live extraction was performed, and no accuracy benchmark is claimed.

The Kimi API developer guide covers broader integration context. Here, the working question is narrower: what evidence should an application require before accepting extracted document text as adequate input for table-based Q&A?

Notebook entry 1: identify what the API actually returns

Kimi's file-based Q&A guide describes uploading a file with purpose="file-extract", retrieving its content, and including that content in the conversation. In that workflow, the prompt receives extracted text, not merely a file ID.

The Get File Content reference specifies Markdown-formatted text from /v1/files/{file_id}/content. It describes formatting such as headings, lists, and tables. Markdown formatting is useful evidence of structure, but it is not a guarantee that every relationship in a particular source survived correctly.

Treat the output as a document representation requiring inspection. A readable paragraph may still have lost a superscript. A plausible table may attach the right number to the wrong instrument. Extraction success and task adequacy need different statuses in your application.

The Upload File reference distinguishes text extraction from image and video purposes. It currently directs image understanding to purpose="image" instead of image content extraction. Do not infer native visual understanding from the fact that a file object exists. The chosen upload purpose and subsequent request representation determine which path you are testing.

Notebook entry 2: write the source facts before inspecting output

For an acceptance experiment, first make a small reference record from the source document. A person should verify that record against the source. Otherwise, a parser and a model can agree with each other while both disagreeing with the document.

Here is the complete synthetic source table for this notebook. Its title is Calibration register. Its physical source page is deliberately unspecified: the example has no actual PDF pages.

SensorLocationTolerance (°C)
S-014Cold room0.4
S-029Loading bay—

The source note reads: A dash means not calibrated. These values are illustrative test data, not measurements from an actual facility. The intended question is, “Which sensor has a stated tolerance, and what does the dash mean?”

The acceptance record needs more than the strings 0.4 and S-014. It needs their relationship, the unit in the column header, and the rule attached to the dash. The location column helps detect a row shift that might otherwise preserve every number in the document.

Write the expected result before running extraction. In this fixture, S-014 has the stated tolerance of 0.4 °C. S-029 has no stated numeric tolerance, because the note says it is not calibrated. This is a specification for the test, not an observed model answer.

Notebook entry 3: compare representations, not impressions

When extracted text arrives, inspect the evidence that the intended question requires. The following comparison contains hypothetical defects, not reported Kimi failures.

Source factHypothetical extracted representationIngestion decision
Header contains °CHeader becomes only “Tolerance”Hold: unit evidence is missing
S-014 aligns with 0.40.4 appears on the S-029 rowHold: the relationship changed
Dash means not calibratedNote is absentHold: missing-value interpretation is unsupported
Two distinct sensor IDsOne row is duplicatedHold: source coverage is uncertain
Title identifies the registerTitle is preserved with both rowsOne necessary check passes

A passing title check does not compensate for a failed row relationship. Avoid averaging critical checks into a score that can conceal a dangerous omission. For this small fixture, every required relationship must pass before the representation is admitted to Q&A.

This differs from asking the model to extract rows directly from visual document input. The Gemini PDF table-extraction article discusses that adjacent workflow. Here, we are inspecting an intermediate Markdown artifact before Kimi sees it in a text conversation. That boundary lets you identify whether a later failure began during extraction, prompt construction, or answer generation.

Notebook entry 4: run an offline acceptance cell

This Python cell validates the deliberately simple Markdown fixture and records content digests. It makes no network request and requires no credentials. The parser supports only this three-column pipe table: it does not support escaped pipes, merged cells, HTML tables, or arbitrary Markdown. Those cases need a suitable parser and separately reviewed mappings.

import hashlib
import json

REFERENCE = {
    "title": "Calibration register",
    "header": ["Sensor", "Location", "Tolerance (°C)"],
    "rows": {"S-014": ["Cold room", "0.4"],
             "S-029": ["Loading bay", "—"]},
    "note": "A dash means not calibrated.",
}
GOOD = """# Calibration register
| Sensor | Location | Tolerance (°C) |
| --- | --- | --- |
| S-014 | Cold room | 0.4 |
| S-029 | Loading bay | — |
A dash means not calibrated.
"""


def digest(data):
    return hashlib.sha256(data).hexdigest()


def inspect(markdown):
    lines = [line.strip() for line in markdown.splitlines()]
    table = [line for line in lines if line.startswith("|")]
    cells = [[cell.strip() for cell in line.strip("|").split("|")]
             for line in table]
    checks = {
        "title": "# " + REFERENCE["title"] in lines,
        "header": bool(cells) and cells[0] == REFERENCE["header"],
        "note": REFERENCE["note"] in lines,
    }
    rows = cells[2:]
    shape_ok = len(cells) >= 2 and all(len(row) == 3 for row in rows)
    ids = [row[0] for row in rows] if shape_ok else []
    checks["row_identity"] = (shape_ok and len(ids) == len(set(ids))
                              and set(ids) == set(REFERENCE["rows"]))
    checks["relationships"] = (checks["row_identity"] and
        {row[0]: row[1:] for row in rows} == REFERENCE["rows"])
    reference_bytes = json.dumps(REFERENCE, ensure_ascii=False,
                                 sort_keys=True).encode("utf-8")
    return {
        "fixture_kind": "synthetic_markdown",
        "reference_sha256": digest(reference_bytes),
        "extracted_sha256": digest(markdown.encode("utf-8")),
        "checks": checks,
        "admit_to_qa": all(checks.values()),
    }


accepted = inspect(GOOD)
assert accepted["admit_to_qa"] is True
missing_unit = GOOD.replace("Tolerance (°C)", "Tolerance")
assert inspect(missing_unit)["admit_to_qa"] is False
shifted = GOOD.replace("Cold room | 0.4", "Cold room | —")
shifted = shifted.replace("Loading bay | —", "Loading bay | 0.4")
assert inspect(shifted)["checks"]["relationships"] is False
assert inspect(GOOD.replace(REFERENCE["note"], ""))["admit_to_qa"] is False
print("Offline ingestion fixtures passed")

The assertions show that the validator detects the defects we intentionally introduced. They do not establish the extractor's accuracy on real files. The reference is also part of the evaluation: an incorrect reference can approve incorrect output. Keep its reviewer and revision with the acceptance record.

Exact string matching is appropriate for this controlled example. A production workflow may need carefully documented equivalence rules for whitespace or typography. Apply those rules to specific fields; a global cleanup that removes punctuation can turn a range into a number or make distinct identifiers look identical.

Notebook entry 5: preserve evidence through prompt construction

After acceptance, freeze the extracted representation and record its digest. If you later remove headers, normalize whitespace, or split a table into chunks, the model receives a different representation. Record a second digest for the text actually inserted into the request. A digest identifies content; it does not prove that content is correct.

Keep an ingestion receipt with the source-file digest, provider file ID when applicable, extraction retrieval time, raw extracted-text digest, transformation version, prompt-text digest, and reference revision. These are proposed application fields, not a native Kimi response schema. Their purpose is to make later comparisons possible without relying on a filename that might have been reused.

Do not invent page numbers when extraction has not supplied a verified page mapping. Instead, use an application locator such as document revision, table title, sensor ID, and a retained excerpt. Label that locator for what it is. A real source-page reference can be added only when your ingestion process has checked the mapping.

For long documents, keep a table with its header and interpreting notes when forming a chunk. If the required evidence will not fit, select a smaller task or retrieve the relevant section with its context. The Chinese LLM selection guide offers the broader principle: evaluate the actual workload and route, rather than relying on a model-family label.

Notebook entry 6: ask a question that can expose loss

A useful pilot prompt requests both an answer and its supporting row. Ask which sensor has a stated tolerance, request the original unit, and ask what evidence explains the dash. Require an explicit “not available in the supplied text” response when the needed evidence is absent.

Keep application instructions separate from document material. Treat the document as evidence, including when it contains sentences that look like instructions. Tell the model which question to answer and which source region to use. Delimit the document clearly, but do not assume delimiters alone establish a security boundary.

The Chat Completions reference documents the conversation request structure. Use the supported structure for the chosen model and route. The key ingestion requirement remains unchanged: the accepted extracted content must actually be present in the submitted messages. Logging only a file ID or an application filename cannot demonstrate that.

If the retained source text lacks layout evidence necessary to answer, changing the prompt cannot recreate that evidence reliably. Consider a separate visual-input experiment following the Kimi vision guide, which documents multimodal message parts. Treat that as a different request path with its own acceptance tests, rather than silently claiming the original text extraction understood the page visually.

Notebook entry 7: budget the request and separate outcomes

Measure input after assembling instructions, selected document text, the question, and required history. Kimi documents an input token-estimation endpoint. Verify availability for the account and route before depending on it; do not substitute a page count for the actual request representation.

Reserve enough capacity for the intended answer under the selected model's current limits. If you shorten the text after estimating, record that transformation and rerun the ingestion checks relevant to the retained material. The Claude token-budgeting article describes the same application concern in another provider context; its endpoint and parameters should not be copied into Kimi requests.

If you compare two model configurations, feed them the same accepted representation and keep the question fixed. Otherwise, a different extraction or cleanup step can masquerade as a model-quality difference. For an extractor comparison, keep the model request fixed after each representation passes the same source checks. State which boundary changed in each experiment. A result should answer one question at a time, so a future reviewer can understand what the evidence actually supports.

Keep three outcomes in the notebook: extraction returned content, the representation passed its acceptance checks, and the model answered correctly from that representation. A failed answer with correct extracted evidence suggests a different investigation from a wrong answer built on a missing header.

Use the Chinese LLM API acceptance guide to extend the evaluation beyond this fixture. Add real documents you are authorized to process, including repeated headers, footnotes, and missing values. Report actual results only after running and reviewing them.

Close the notebook with one verified route

For a live trial, configure credentials, base URLs, and model IDs from the account's current documentation. This article executed no live upload or model request. Begin with a non-sensitive source and retain the extracted artifact before asking one checkable question.

Before choosing Treerouter for the trial, confirm account and route support separately for Files upload, content retrieval, the selected chat interface, and any token-estimation or visual-input feature you need. Those advanced capabilities are unverified here. Support for a basic model call does not establish support for the entire ingestion workflow.

If a verified route accepts only text generation, an authorized extraction stage can be evaluated separately and its accepted text supplied through that route. Record the two stages explicitly. Register or configure the confirmed route, complete the first model call, then advance only when the source-to-answer evidence remains inspectable.

Learn more: Treerouter.