api-llm-ocr

To install the project, clone the repository, set up a Python virtual environment, and install the required dependencies via pip.

git clone https://github.com/yigitkonur/api-llm-ocr.git
cd api-llm-ocr

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

You can run the application using several different methods depending on your preferred entry point. The API will be available at http://127.0.0.1:8000 by default, with auto-generated documentation at /docs.

# Option 1: Uvicorn reload
uvicorn main:app --reload

# Option 2: Swift OCR app factory
uvicorn swift_ocr.app:app --reload

# Option 3: Python module entry point
python -m swift_ocr

# Option 4: CLI with custom host, port, and workers
python -m swift_ocr --host 0.0.0.0 --port 8080 --workers 4

You can adjust the BATCH_SIZE and MAX_CONCURRENT_OCR_REQUESTS to achieve different goals:

• High accuracy: Set BATCH_SIZE=1 (best for complex tables).
• Balanced: Set BATCH_SIZE=5 and MAX_CONCURRENT_OCR_REQUESTS=10.
• Max throughput: Set BATCH_SIZE=10 and MAX_CONCURRENT_OCR_REQUESTS=20 (monitor rate limits closely).

The application requires specific environment variables to connect to OpenAI or Azure OpenAI vision models. Create a .env file in the root directory with the following configuration.

# required
OPENAI_API_KEY=your_api_key
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
OPENAI_DEPLOYMENT_ID=your_vision_model_deployment

# optional
OPENAI_API_VERSION=gpt-4o
BATCH_SIZE=1
MAX_CONCURRENT_OCR_REQUESTS=5
MAX_CONCURRENT_PDF_CONVERSION=4

The main.py file serves as a backward compatibility entry point for the API. You can run the FastAPI application using uvicorn targeting this file. This is useful if you are migrating from an older version of the service that expected the main:app target.

uvicorn main:app --reload

The core logic and FastAPI application reside in the swift_ocr package. For the most direct way to run the service, use the swift_ocr.app module or run the package as a module.

# Run via uvicorn targeting the package app
uvicorn swift_ocr.app:app --reload

# Or run the package directly as a module
python -m swift_ocr

If you encounter issues, check the following common solutions:

• Missing environment variables: Ensure .env contains OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, and OPENAI_DEPLOYMENT_ID.
• 429 Rate Limits: Reduce MAX_CONCURRENT_OCR_REQUESTS or BATCH_SIZE.
• Timeout errors: Large PDFs take time; the system has built-in backoff, but you may need to wait.
• Garbled output: Verify the PDF is not password-protected or corrupted.
• Tables misformatted: Use BATCH_SIZE=1 for complex table layouts.
• Failed to init client: Verify the AZURE_OPENAI_ENDPOINT format (e.g., https://your-resource.openai.azure.com/).

To process a remote PDF, send a POST request to the /ocr endpoint with a JSON body containing the url key.

curl -X POST "http://127.0.0.1:8000/ocr" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/document.pdf"}'

To process a local PDF file, send a POST request to the /ocr endpoint using multipart/form-data with a field named file.

curl -X POST "http://127.0.0.1:8000/ocr" \
  -F "file=@/path/to/document.pdf"

A successful OCR request returns a JSON object containing the extracted markdown text, the processing status, the number of pages processed, and the total processing time in milliseconds.

{
  "text": "# document title\n\n## section 1\n\nextracted text...",
  "status": "success",
  "pages_processed": 5,
  "processing_time_ms": 1234
}

The following HTTP status codes are returned by the OCR API:

| code | meaning |
|:---|:---|
| `200` | success |
| `400` | bad request (no file/URL, or both provided) |
| `422` | validation error |
| `429` | rate limited — retry with backoff |
| `500` | processing error |
| `504` | timeout downloading PDF |

The following environment variables can be used to tune the performance and accuracy of the OCR engine:

| variable | default | description |
|:---|:---|:---|
| `OPENAI_API_KEY` | — | API key |
| `AZURE_OPENAI_ENDPOINT` | — | endpoint URL |
| `OPENAI_DEPLOYMENT_ID` | — | vision model deployment ID |
| `OPENAI_API_VERSION` | `gpt-4o` | API version |
| `BATCH_SIZE` | `1` | pages per OCR request (1-10). higher = faster, less accurate |
| `MAX_CONCURRENT_OCR_REQUESTS` | `5` | parallel OCR calls |
| `MAX_CONCURRENT_PDF_CONVERSION` | `4` | parallel page renders. match your CPU cores |