批次摘要 API 匯出的租戶歸屬:3 項檢查
Tenant Attribution for Batch Summarization API Export (3 Checks)
批次摘要 API 匯出應保留由應用程式管理的租戶與提交項目對應關係,並按明確的項目識別碼核對非同步結果,再供候選人審閲及匯出。匯出前須確認結果均屬於已提交項目、所有提交項目均有交代,且每筆成本均標明實際來源與範圍;批次總額不能當作個別文件的實際費用。
An e-commerce hiring service needs to explain which tenant paid for summarizing each candidate's documents before those summaries enter a job-rubric scoring workflow. A completed async job doesn't answer that question. Neither does a downloadable file.
TL;DR: Queue multiple documents for batch summarization, keep one summarization prompt across items, and preserve an application-owned tenant-to-item mapping through result collection and export. Make three checks before candidate scoring: every result belongs to a submitted item, every submitted item is accounted for, and every attributed cost has an explicit source and scope.
Start with attribution.
The useful output is a summary attached to the right candidate and tenant, with enough evidence to explain its cost. A score comes later. This pipeline prepares evidence for scoring; it does not establish that a summary is sufficient to evaluate a person.
How should a batch summarization API export results for multiple documents?
Before: a web request loops through candidate documents, collects summaries, and leaves someone to reconcile the bill afterward.
After: the request hands off a batch. The application retains the relationship between tenant, candidate, document, and submitted item. Processing happens asynchronously. Result collection and the administrator's download are separate steps.
Diagram in words: tenant submission → item ledger → async batch → status polling → result reconciliation → candidate review and export. Cost evidence joins the ledger at the scope where it was actually reported.
Scope matters.
A batch-level amount cannot establish each document's actual charge. Dividing a total evenly might be an allocation policy, but it isn't an observation of individual calls. For an illustrative dataset, imagine two tenants, three candidate documents, and one rubric version. Two documents belong to one candidate at shop-a; the third belongs to another candidate at shop-b. If one submission processes all three, copying its entire reported cost to each tenant would count the same amount twice. Dividing it by three avoids that particular duplication but still makes an assumption about the cost of each document. Neither operation discovers a missing observation. The export should label an allocation as an allocation and preserve its policy separately from observed cost evidence.
Those numbers are example inputs, not production measurements.
Keep the rubric version alongside the summarization prompt version so reviewers can identify the transformation that produced their evidence. Use the same summarization instruction across items; candidate documents supply the variable content. That makes output shape more consistent and easier to parse.
Start the integration with a copyable schema check
Check the contract first.
The TypeScript example below retrieves the public discovery manifest before an application builds its batch adapter. It is a real read request, not a fabricated batch-submission payload. Configure INFRAI_BASE_URL to the documented HTTPS API base ending in /v1, without a trailing slash, and supply INFRAI_API_KEY through the environment. The discovery surface is public and needs no key; this example includes Bearer authentication to demonstrate the credential convention used for authenticated calls.
Save the file and run it in a TypeScript-capable runtime with a global fetch implementation. There are no packages to install. The response is printed without assuming undocumented batch fields. Use the manifest's path fields and the capability-specific request and response schemas when implementing submission, polling, collection, and export.
async function main() {
const baseURL = process.env.INFRAI_BASE_URL;
const apiKey = process.env.INFRAI_API_KEY;
if (!baseURL || !apiKey) {
throw new Error("Set INFRAI_BASE_URL and INFRAI_API_KEY");
}
const parsed = new URL(baseURL);
if (parsed.protocol !== "https:" || parsed.pathname !== "/v1") {
throw new Error("Use the documented HTTPS API base ending in /v1");
}
const wait = (ms: number) =>
new Promise<void>(resolve => setTimeout(resolve, ms));
for (let attempt = 0; attempt < 4; attempt++) {
const response = await fetch(baseURL + "/discovery", {
method: "GET",
headers: { Authorization: `Bearer ${apiKey}` },
redirect: "error",
});
if (response.status === 429 && attempt < 3) {
const retryAfter = response.headers.get("Retry-After");
let retryMs = 0;
if (retryAfter !== null) {
const seconds = Number(retryAfter);
retryMs = Number.isFinite(seconds)
? Math.max(0, seconds * 1000)
: Math.max(0, Date.parse(retryAfter) - Date.now());
}
const delay = Math.max(
500 * 2 ** attempt,
Number.isFinite(retryMs) ? retryMs : 0,
);
await response.text();
await wait(delay);
continue;
}
const body = await response.text();
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${body}`);
}
console.log(JSON.stringify(JSON.parse(body), null, 2));
return;
}
}
main().catch(error => {
console.error(error instanceof Error ? error.message : String(error));
process.exitCode = 1;
});
This read is safe to retry. It honors Retry-After as either seconds or a date and uses exponential backoff when retrying a rate-limited request. Four attempts bound the example.
Submission is a separate operation. For writes, use the documented idempotency convention so retries do not create duplicate work. A retry policy and a deduplication policy solve different problems.
Once the adapter exists, teach reconciliation with the three-document fixture above. Return the results in a different order from submission. Join by an explicit submitted-item identifier, reject unknown identifiers, and identify duplicates before exporting. A result at array position zero must not inherit the tenant at submission position zero.
Keep the application ledger authoritative for ownership.
For the third check, retain the source and scope of each cost observation. If the integration has only a batch-level amount, keep it at batch scope until an explicit allocation policy applies. A missing item-level amount remains unavailable; zero would assert something different.
Choose an integration by the evidence it preserves
Batch submission is the easiest backend pattern for a beginner summarizing many documents at once. Queue the collection, poll status, collect outputs after completion, and request downloadable results for the administrative workflow.
Compare the alternatives using that same collection.
OpenAI Batch, Anthropic Message Batches, and Gemini Batch are real options to evaluate. Their official documentation is linked below. Treat their input contracts, result handling, and accounting evidence as separate integration questions; a common application ledger does not make provider payloads interchangeable.
| Option | Where to evaluate it | Boundary before choosing |
|---|---|---|
| OpenAI Batch | A summarization workflow targeting OpenAI | Verify returned item identifiers and the usage evidence your tenant ledger needs |
| Anthropic Message Batches | A rubric workflow being evaluated with Anthropic models | Verify its request/result contract rather than reusing another provider's payload |
| Gemini Batch | A document workflow being evaluated with Gemini | Check its input/output contract and build the corresponding result adapter |
| Shared REST backend | A plain REST API needs no SDK. One key, one wallet, one bill cover 295 routes across 20 modules. This unified API means the hiring backend can use a single key for multiple backend capabilities and reconcile a single bill before allocating costs to tenants. Public discovery is self-describing and requires no key | Verify the batch-specific schema and accounting scope before claiming item-level attribution |
Infrai offers one key, one bill, and a plain REST API with no SDK to install: a single key and unified billing across multiple backend services. This is the shared REST backend in the table. Its single API key covers 295 routes across 20 modules, so the hiring backend can reconcile a single invoice before allocating charges to tenants. That does not replace the application's per-tenant ledger. The public, self-describing discovery API requires no key and supplies request JSON Schema, response schemas, billing details, and runnable examples. That lets the team inspect the contract before wiring the export adapter and identify which returned evidence its tenant ledger can actually consume. Runnable examples in 10 languages also let colleagues inspect the same capability without adopting the TypeScript application's client library. Specified per-call cost, vendor, latency, and request metadata support instrumentation. A per-call cost still needs an explicit relationship to the documents inside that call.
Don't guess granularity.
The direct provider options deserve evaluation when those providers are already candidates for the underlying model work. The shared REST interface fits a team that wants an HTTP integration and inspectable schemas across backend capabilities. This is an integration decision, not a measured performance ranking. Model suitability for rubric evidence still requires its own evaluation.
Does a successful export mean the tenant ledger is complete?
No.
Export is a delivery step. Compare collected identifiers with the submission ledger before presenting a download as complete. In the illustrative fixture, all three documents must be accounted for, including both documents belonging to the same candidate.
There is a useful trade-off here. Refusing an incomplete collection makes the invariant easy to teach. Retaining partial progress is friendlier for a large administrative job, but the interface must identify missing items and avoid calling that collection ready for complete scoring. An export intended for reviewing summaries can disclose unresolved cost attribution. An export intended for tenant accounting needs that gap resolved or explicitly recorded under an agreed allocation policy.
For observability, track missing summaries and missing attribution separately. A completed-job count answers an operational question; a reconciled-document count answers another. Do not let either silently stand in for accounting completeness.
Can identical prompts make candidate scoring consistent?
They help keep summary shape consistent and easier to parse. They do not prove that summaries preserve all relevant evidence or that subsequent scores are valid.
Retain the link to the original document and the explicit job rubric. The next useful check is a reviewer inspecting each summary against that source and rubric, with tenant ownership already settled. That preserves the purpose of this workflow: prepare traceable evidence for scoring candidates, while keeping the financial explanation attached to the right tenant.
Sources
References for comparing current provider interfaces and their contracts:
來源:DEV Community · dev.to