Files API, העלאה ועיבוד מסמכים בקנה מידה

הבעיה: שולחים קובץ של 5MB, 20 פעם ביום

תאר לעצמך שיש לך מערכת שמנתחת חוזי שכירות. כל בוקר מגיעים 30 חוזים, וכל חוזה נשאל עליו 10 שאלות שונות, פרטי שוכר, תנאי יציאה, סעיפי עדכון מחיר. ללא Files API, הקוד שלך שולח את אותו PDF של 3MB לכל אחת מ-10 השאלות: 30 בקשות, 30 פעמים 3MB, 90MB של bandwidth לכל חוזה בודד.

Files API פותר זאת: מעלים פעם אחת, מקבלים file_id, ושולחים רק את ה-ID בכל הבקשות הבאות. אחסון בשרתי Anthropic, גישה מיידית, ללא שליחה חוזרת.

איך Files API עובד, הזרימה המלאה

שלושה שלבים בלבד: Upload → Use → Delete.

import anthropic

client = anthropic.Anthropic()

# שלב 1: העלאה פעם אחת
with open("contract-dizengoff-apt.pdf", "rb") as f:
    file_obj = client.beta.files.upload(
        file=("contract-dizengoff-apt.pdf", f, "application/pdf")
    )
file_id = file_obj.id
# file_id = "file_011CNha8iCJcU1wXNR6q4V8w"

# שלב 2: שאלות מרובות, אותו file_id
questions = [
    "מי השוכר ומה תאריך תחילת החוזה?",
    "מה תנאי היציאה המוקדמת?",
    "האם יש סעיף עדכון שכר דירה לפי מדד?"
]

for q in questions:
    response = client.beta.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=512,
        messages=[{
            "role": "user",
            "content": [
                {"type": "text", "text": q},
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": file_id}
                }
            ]
        }],
        betas=["files-api-2025-04-14"]
    )
    print(f"{q}\n{response.content[0].text}\n")

# שלב 3: מחיקה אחרי שימוש
client.beta.files.delete(file_id)

שים לב לשני דברים קריטיים: (1) betas=["files-api-2025-04-14"], בלי זה הבקשה נכשלת. (2) בלוק document עם source.type = "file", לא base64, לא URL, רק file_id.

פורמטים נתמכים, ומה לעשות עם האחרים

שגיאה נפוצה: מפתחים שמעלים תמונה ואז משתמשים ב-"type": "document" מקבלים שגיאת 400. תמונות דורשות "type": "image". כלל פשוט: PDF ו-text = document, תמונה = image.

ניהול קבצים, list, retrieve, delete

# רשימת כל הקבצים ב-workspace
files = client.beta.files.list()
for f in files.data:
    print(f"{f.id} | {f.filename} | {f.size:,} bytes")

# מידע על קובץ ספציפי
info = client.beta.files.retrieve_metadata(file_id)
print(f"נוצר: {info.created_at}")

# מחיקה
client.beta.files.delete(file_id)
print("נמחק")

חשוב לדעת על מגבלות האחסון: 500 MB לקובץ בודד500 GB לארגון. פעולות ה-Files API עצמן (upload, list, delete) הן חינמיות. מה שמחויב הוא השימוש בקובץ בתוך בקשות Messages, כ-input tokens רגיל. קבצים לא נמחקים אוטומטית, נשמרים עד שמוחקים אותם ידנית.

דוגמה ישראלית: ניתוח חוזי שכירות בקנה מידה

משרד תיווך בתל אביב מנהל 200 נכסים. בכל חודש נחתמים 40-50 חוזים חדשים, וצוות ה-back-office צריך לאמת שכל חוזה עומד בתקנות הגנת הדייר. הפתרון: pipeline עם Files API שמעלה כל חוזה, מריץ 8 בדיקות אחידות, ומוחק את הקובץ. עלות: שליחה אחת של bandwidth, לא 8. זמן: מקביל, לא סדרתי.

def analyze_contract(pdf_path: str) -> dict:
    """מנתח חוזה שכירות ל-8 נקודות בדיקה"""
    with open(pdf_path, "rb") as f:
        file_obj = client.beta.files.upload(
            file=(pdf_path.split("/")[-1], f, "application/pdf")
        )

    checks = [
        "מה שם השוכר ות.ז. שלו?",
        "מה תאריך תחילת ותום החוזה?",
        "מה סכום השכירות החודשי?",
        "האם יש סעיף הצמדה למדד?",
        "מה גובה הערבות הבנקאית?",
        "מה תנאי היציאה המוקדמת?",
        "האם יש סעיף איסור בעלי חיים?",
        "האם יש סעיף ביטוח דירה חובה?"
    ]

    results = {}
    for check in checks:
        resp = client.beta.messages.create(
            model="claude-haiku-4-5",
            max_tokens=200,
            messages=[{
                "role": "user",
                "content": [
                    {"type": "text", "text": check + " ענה בקצרה."},
                    {"type": "document",
                     "source": {"type": "file", "file_id": file_obj.id}}
                ]
            }],
            betas=["files-api-2025-04-14"]
        )
        results[check] = resp.content[0].text

    client.beta.files.delete(file_obj.id)
    return results

שים לב לבחירת המודל: לבדיקות אחידות על מסמכים claude-haiku-4-5 מהיר וזול. לניתוחים מורכבים שדורשים שיפוט, עבור ל-Sonnet.

Files API + Prompt Caching, שני כלים שונים

נשאלת שאלה נפוצה: האם Files API חוסך tokens? לא ישירות. כל פעם שמשתמשים ב-file_id בבקשה, Claude קורא את תוכן הקובץ ומחייב אותו כ-input tokens. מה שחוסך הוא bandwidth ו-latency, לא עלות token.

כדי לחסוך גם tokens, משלבים עם Prompt Caching: כשה-prompt כולל file_id קבוע ובא בעקביות בתחילת ה-messages, Anthropic יכולה לשמור אותו ב-cache ולחייב cache-hit במקום full input. ביחד, השילוב יכול להוריד עלויות ב-70-80% על workloads חוזרים.