OCR API 整合:Python 與 Node 程式碼範例
此處的 OCR API 整合意味著在您的 OCR 引擎之後加入一個 HTTP 請求:您傳送原始識別文字,並取得清理後文字。該端點與 OpenAI 相容,因此您現有的 SDK 只需變更兩個設定即可使用。
更新於

重點摘要
- 將 Base URL 設定為 https://api.llmocrapi.com/v1,使用模型 ID uncensored,並將您的金鑰作為 Bearer token 傳送。
- API 僅接受文字。請先執行您的 OCR 引擎,並將其輸出作為使用者訊息傳送。
- JSON 模式會回傳機器可讀取的結果,最多 8 個執行緒的執行緒池可保持批次處理速度。
- 429 回應是一個等待並重新嘗試的信號,並非失敗:失敗的請求不會計費。
請求在管線中的位置
典型的文件流程包含四個步驟。掃描器或手機相機產生影像,OCR 引擎將影像轉換為原始文字,清理步驟修復該文字,你的應用程式儲存或搜尋結果。此處描述的 API 是第三步。它不會接收影像,也沒有影像輸入。當你在意原始掃描的隱私時,這是一個功能,因為只有文字離開你的機器,這也是一個限制,當你預期有一個處理圖片的單一端點時。
提示詞不會用於訓練。但仍只傳送任務所需的內容:如果清理不依賴帳號號碼或姓名,請在呼叫前將其移除。
在編寫任何程式碼之前,取得 API 金鑰。新用戶註冊後,只需點擊該頁面即可領取 $0.50 的免費試用額度,足以多次執行以下所有範例。試用金鑰允許 2 個並行請求和每分鐘 60 個請求;完整金鑰允許 8 個和 300 個。
您需要設定的項目
| 設定 | 說明 |
|---|---|
| Base URL | https://api.llmocrapi.com/v1 |
| 端點 | POST /v1/chat/completions |
| 模型 ID | uncensored |
| Auth 標頭 | Authorization: Bearer YOUR_KEY |
| 上下文視窗 | 100,000 token,含提示詞與補全 |
將金鑰儲存在環境變數中,不要放在原始碼控制系統中。範例會讀取 LLMOCR_API_KEY。
開始前有兩個實用注意事項。將金鑰排除在前端程式碼之外,因為任何傳送至瀏覽器的內容都可能被其使用者讀取;請從伺服器或worker呼叫 API。並儘早決定原始 OCR 文字與清理後文字將存放於何處,因為清理後的輸出是您將搜尋、索引並展示給人們的檔案,而原始文字則是若更正受到質疑時的證據。
使用 curl 的第一次請求
從 curl 開始,以便在 SDK 隱藏請求的原始形狀之前看到它。下方的範例是一個典型的損壞 OCR 片段:連字號跨換行符號斷開、字母與數字混淆,以及雜亂的頁碼。
curl https://api.llmocrapi.com/v1/chat/completions \
-H "Authorization: Bearer $LLMOCR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"temperature": 0,
"messages": [
{"role": "system", "content": "You repair raw OCR text. Fix broken words, rejoin hyphenated line breaks, remove page numbers. Return only the corrected text."},
{"role": "user", "content": "The inven-\ntory was com1leted on Tuesday.\n\n- 14 -\n\nA second ship-\nment arrived."}
]
}'
回覆遵循標準的 chat completion 格式。清理後文字位於 choices[0].message.content,usage 提供該請求的提示詞與完成 token。將 temperature 設為 0 以進行清理。你希望相同的輸入產生相同的輸出,而非創意的變化。
Python 搭配 OpenAI SDK
使用 pip install openai 安裝 SDK。僅建構子與標準 OpenAI 設定不同。
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.llmocrapi.com/v1",
api_key=os.environ["LLMOCR_API_KEY"],
max_retries=4,
)
SYSTEM = (
"You repair raw OCR text. Fix broken words, rejoin hyphenated line breaks, "
"remove page numbers and running headers. Do not add or remove facts. "
"Return only the corrected text."
)
def clean(raw: str) -> str:
resp = client.chat.completions.create(
model="uncensored",
temperature=0,
messages=[
{"role": "system", "content": SYSTEM},
{"role": "user", "content": raw},
],
)
return resp.choices[0].message.content
print(clean("The inven-\ntory was com1leted on Tuesday."))
max_retries 參數會指示 SDK 在連線錯誤與 429 回應時以退避策略重試,因此輕量使用時你不需要自行撰寫該迴圈。
Node.js 範例
使用 npm install openai 和 ES 模組,相同的呼叫如下所示。
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.llmocrapi.com/v1",
apiKey: process.env.LLMOCR_API_KEY,
});
export async function clean(raw) {
const resp = await client.chat.completions.create({
model: "uncensored",
temperature: 0,
messages: [
{ role: "system", content: "Repair raw OCR text. Return only the corrected text." },
{ role: "user", content: raw },
],
});
return resp.choices[0].message.content;
}
console.log(await clean("A second ship-\nment arrived."));
任何支援 OpenAI 聊天格式的客戶端,例如無程式碼自動化工具或現有的內部包裝程式,都可以使用相同的兩個設定。文件 列出了所有支援的參數。
使用 JSON 模式的結構化輸出
自由文字適合存檔,但資料擷取管線需要欄位。開啟 response_format 以啟用 JSON 模式,並在提示詞中描述您想要的形狀。在指示和設定中都要求 JSON 會產生最可靠的結果。
import json
resp = client.chat.completions.create(
model="uncensored",
temperature=0,
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": (
"Clean the OCR text of a receipt and answer in JSON with keys "
"'vendor' (string), 'date' (YYYY-MM-DD or null), 'total' (number or null), "
"'cleaned_text' (string)."
)},
{"role": "user", "content": raw_receipt_text},
],
)
data = json.loads(resp.choices[0].message.content)
始終將 json.loads 包裝在 try 區塊中並保留原始文字,因為非常長或截斷的回應仍可能產生無效的 JSON。如果解析失敗,重新嘗試一次,然後將該頁面排入人工審查佇列。
並行處理批次
一次處理一個請求對於數千個頁面來說太慢。完整金鑰允許 8 個並行請求,因此 6 或 8 個工作執行緒的執行緒池可讓你保持在限制內。如果同一個金鑰也被其他用途使用,請保留一些緩衝空間。
from concurrent.futures import ThreadPoolExecutor
pages = [open(f"ocr/page_{i:04d}.txt").read() for i in range(1, 501)]
with ThreadPoolExecutor(max_workers=6) as pool:
cleaned = list(pool.map(clean, pages))
for i, text in enumerate(cleaned, start=1):
open(f"clean/page_{i:04d}.txt", "w").write(text)
如果您超過限制,API 會回傳 HTTP 429。錯誤代碼 rate_limited 表示每分鐘請求過多,concurrency 表示同時請求過多。帶有 Retry-After: 5 標頭的 429 表示暫時過載:等待五秒。串流請求會保留一個並行槽位直到串流結束,因此請關閉您停止讀取的串流。
在長時間執行時請留意 X-Balance-USD 回應標頭。當餘額偏低時,請暫停並前往 定價頁面 儲值,避免任務中途失敗。
長文件與檢查輸出
實際的 OCR 輸出很少是單一整齊的頁面。掃描的書籍會產生數千頁,且損壞不均勻:一個乾淨的章節,然後是一頁充滿斷裂字元的污漬頁面。一些習慣可保持清理步驟的可預測性。
按結構分割,而非按字元數量。在頁面斷行或段落邊界處切斷,以便模型在區塊開頭不會收到半個句子。如果句子跨越頁面邊界,請將前一頁的最後一段作為唯讀上下文包含在內,並指示模型只傳回當前頁面。這會增加每個請求的少量輸入 token,每 1M token 價格為 $0.15,幾乎可以忽略不計,且能修復跨越兩個頁面的連字號單字。
在接受結果之前,請以低成本檢查來驗證每個結果。將清理後文字的長度與原始內容比較:比例遠大於或遠小於 1 表示模型遺漏或捏造了內容。比較數字:從兩個版本中提取所有數字序列,並標記有差異的頁面,因為日期、金額和識別碼的遺漏是最嚴重的錯誤。將原始 OCR 結果保留在清理後文字旁邊,以便人員隨時重建引擎實際看到的內容。
最後,將第一次運行視為試行。清理 20 頁,親自閱讀其中 10 頁,並調整系統提示詞。通常對指示進行兩三次編輯比任何參數變更更能提升品質。
常見錯誤
- 一次傳送非常大的頁面。上下文視窗為 100,000 token,最大請求主體為 8 MB,但以頁面大小的區塊處理準確度更好,且失敗的區塊重做的成本較低。
- 讓模型改寫。 如果提示詞未明確指示不得增減事實,它可能會修飾受損的段落。保持指示明確並比較長度:如果清理後的頁面遠短於其來源,值得檢查。
- 使用錯誤的模型名稱。 唯一的模型 ID 是
uncensored。您可以使用GET /v1/models列出模型。 - 預期嵌入或圖片輸入。 此 API 均不存在。若要對清理後文字進行搜尋,請使用單獨的嵌入工具。
- 忘記記錄請求 ID。 每個回應都包含
X-Request-Id標頭。請將其與頁面一併儲存,以便支援團隊追蹤不良結果。
內容規則很簡單:該模型針對合法成人用途進行調整,不會拒絕回答;但涉及未成年人的性內容絕對禁止。關於特定案例的問題請聯絡支援。
更多指南
問答
我需要特殊的 SDK 嗎?
否。只要將 Base URL 設定為 https://api.llmocrapi.com/v1、使用模型 ID uncensored 並傳送 Bearer 金鑰,任何 OpenAI SDK 或 HTTP 用戶端均可運作。
我可以直接傳送圖片或 PDF 嗎?
不行。API 僅接受文字。請先執行 OCR 引擎,然後將其輸出作為訊息內容傳送。
我可以同時執行多少個請求?
完整金鑰允許 8 個並行請求和每分鐘 300 個請求。試用金鑰允許 2 個並行請求和每分鐘 60 個。
如果我達到速率限制會發生什麼事?
你會收到 HTTP 429,代碼為 rate_limited 或 concurrency。請等待後重試;未成功完成的請求不會計費。
只差一張表單,即可取得金鑰
建立帳號、複製金鑰、更改基礎 URL。這就是整個設定過程。