توسط Matt Connor 2026-07-15 · به‌روزرسانی شده 2026-08-07

آموزش اتصال به Claude API و اجرای اولین برنامه روی VPS

Q: چگونه کلید API خود را روی سرور امن نگه دارم؟

هرگز آن را در کد، در git، یا خروجی .bashrc قرار ندهید و هرگز در shell تایپ نکنید تا در تاریخچه (history) ذخیره نشود. آن را در فایلی با مالکیت root و دسترسی 600 قرار دهید، برای هر پردازش بهصورت جداگانه بارگذاری کنید، از یک اسکریپت wrapper برای استفاده تعاملی بهره ببرید، از EnvironmentFile= برای systemd استفاده کنید و برای هر سرور یا پروژه یک کلید مجزا در نظر بگیرید تا در صورت نشت کلید، ابطال آن یک جراحی کوچک باشد، نه یک قطع عضو. اگر کلید به هر طریقی در سایتهای اشتراکگذاری متن یا commitهای git قرار گرفت، بلافاصله آن را در Console باطل کنید؛ حذف commit باعث نشتزدایی نمیشود.

Q: با کدام مدل Claude شروع کنم؟

زمانی که در حال ارزیابی کیفیت خروجیها برای توسعه هستید، با claude-opus-4-8 شروع کنید؛ چرا که میخواهید ایده را با بالاترین کیفیت بسنجید و در حجم کاری سرگرمی، تفاوت هزینه تنها در حد چند سنت است. پس از نهایی شدن prompt، ورودیهای واقعی خود را با claude-haiku-4-5 دوباره اجرا کنید؛ برای خلاصهسازی، دستهبندی و اولویتبندی لاگها، این مدل اغلب با یکپنجم قیمت، عملکردی مشابه دارد. مهاجرت به Haiku یا Sonnet را بر اساس اندازهگیری انجام دهید، نه بهصورت پیشفرض.

با این راهنما یک ابزار تحلیل لاگ با Python روی Ubuntu 24.04 بسازید. یاد بگیرید چگونه کلید API را ایمن کنید، استریمینگ را پیاده‌سازی کرده و هزینه‌های مصرفی را کنترل کنید.

آنچه می‌سازید

یک ابزار خط فرمان روی یک VPS تازه با سیستم‌عامل Ubuntu 24.04 که پیام خطا یا بخشی از لاگ را به آن pipe می‌کنید و در مقابل، یک تشخیص به زبان ساده دریافت می‌کنید: journalctl -u nginx -n 50 | explain. این ابزار حدود 60 خط کد Python است و تمام مواردی که یک برنامه واقعی مبتنی بر Claude API به آن نیاز دارد را تمرین می‌کند: یک کلید که به‌درستی ذخیره شده، یک virtualenv، ساختار پاسخ‌های SDK، استریمینگ، زنجیره استثناهای تایپ‌شده و یک unit در systemd تا بدون دخالت شما اجرا شود.

من این پروژه را آگاهانه انتخاب کردم. اکثر آموزش‌های «اولین برنامه API» شما را وادار به ساخت چت‌باتی می‌کنند که دیگر هرگز آن را باز نخواهید کرد. یک تحلیلگر لاگ از همان روز اول روی سرور برای شما کار می‌کند و شما را مجبور می‌کند دو موردی را که مبتدیان واقعاً در آن اشتباه می‌کنند، یاد بگیرید: خواندن صحیح شیء پاسخ و کنترل هزینه‌ها. این API بر اساس توکن صورت‌حساب صادر می‌کند و هیچ سقفی جز آنچه شما تعیین می‌کنید ندارد؛ بنابراین کنترل هزینه در اینجا یک ورودی طراحی است، نه یک فکر ثانویه. این همان انضباطی است که وقتی به مرحله اجرای Claude Code روی همین VPS در tmux می‌رسید، اهمیت پیدا می‌کند.

دریافت کلید API از کنسول

دسترسی به API در کنسول Anthropic به آدرس platform.claude.com مدیریت می‌شود. ثبت‌نام کنید و سپس یک کلید در بخش Settings → API Keys ایجاد نمایید (مستندات مستقیماً به platform.claude.com/settings/keys لینک شده‌اند). کلید فقط یک‌بار نمایش داده می‌شود، با sk-ant- شروع می‌شود و دیگر قابل بازیابی نیست؛ بلافاصله آن را کپی کنید یا در صورت نیاز آن را حذف و دوباره صادر نمایید.

در مورد هزینه‌ها: تا ژوئیه 2026، هیچ سطح رایگان (free tier) دائمی برای API وجود ندارد. مستندات قیمت‌گذاری Anthropic بیان می‌کند که کاربران جدید مقدار کمی اعتبار رایگان برای تست دریافت می‌کنند؛ مقدار دقیق آن همان چیزی است که کنسول هنگام ثبت‌نام به شما نشان می‌دهد و پس از اتمام آن، باید پیش از ارسال درخواست‌ها، حساب خود را شارژ کنید. این موضوع از اشتراک claude.ai جداست؛ طرح‌های Pro یا Max شامل اعتبار API نمی‌شوند و کلید API نیز دسترسی به اپلیکیشن چت را برای شما فراهم نمی‌کند. اگر در حال مقایسه اشتراک با API هستید، این تفاوت موضوعی جداگانه است: کدام طرح Claude واقعاً مورد نیاز شماست.

کلید را محدود به یک پروژه یا سرور خاص ایجاد کنید. اگر کلیدی لو برود—که در بازه زمانی طولانی احتمال آن وجود دارد—شما می‌خواهید آن را بدون مختل کردن سایر دارایی‌های خود ابطال کنید.

کلید را خارج از .bashrc نگه دارید

واکنش غریزی، استفاده از export ANTHROPIC_API_KEY=sk-ant-... در ~/.bashrc است. این کار را نکنید. سه مشکل مجزا وجود دارد:

هر پردازشی آن را به ارث می‌برد. متغیر محیطی که در shell ورود شما export شده باشد، به هر چیزی که اجرا می‌کنید سرایت می‌کند؛ از برنامه وب گرفته تا گزارش‌گر کرش که محیط خود را در گزارش باگ می‌ریزد، یا صفحه phpinfo() که ممکن است کسی فعال گذاشته باشد. سطح در معرض قرارگیری کلید، به «هر چیزی که این کاربر اجرا می‌کند» تبدیل می‌شود.
تایپ کردن آن در ~/.bash_history ثبت می‌شود. اگر یک بار دستور export را دستی اجرا کنید، کلید شما برای همیشه در یک فایل متنی ساده باقی می‌ماند و در تمام نسخه‌های پشتیبان از دایرکتوری home شما همگام‌سازی می‌شود.
هنگام نیاز systemd، کلید در دسترس نیست. سرویس‌ها فایل .bashrc شما را نمی‌خوانند، بنابراین این الگو دقیقاً زمانی شکست می‌خورد که اسکریپت را به یک unit تبدیل می‌کنید؛ معمولاً به شکل یک خطای 401 مرموز در ساعت 6 صبح.

الگوی صحیح در سرور، استفاده از یک فایل محیطی اختصاصی با مجوزهای 600 است که فقط توسط پردازشی که به آن نیاز دارد بارگذاری می‌شود:

sudo mkdir -p /opt/explain
sudo install -m 600 -o root -g root /dev/null /etc/claude-explain.env
printf 'ANTHROPIC_API_KEY=sk-ant-YOUR-KEY-HERE\n' | sudo tee /etc/claude-explain.env >/dev/null

اگر می‌خواهید کلید از فایل‌های swap ویرایشگر دور بماند، به جای ویرایشگر از tee در دستور printf استفاده کنید؛ در هر صورت، با ls -l /etc/claude-explain.env تأیید کنید که فایل دارای مجوز -rw------- است و مالک آن root می‌باشد. shellهای تعاملی کلید را در هر بار فراخوانی از طریق یک wrapper (در زیر) دریافت می‌کنند و systemd آن را از طریق EnvironmentFile= می‌گیرد. root فایل را پیش از کاهش سطح دسترسی (drop privileges) می‌خواند، بنابراین کاربر سرویس هرگز نیازی به دسترسی خواندن آن ندارد. کلید هرگز در کد، در git، در خروجی ps یا در تاریخچه shell ظاهر نمی‌شود.

نصب SDK در یک venv

سیستم‌عامل Ubuntu 24.04 همراه با Python 3.12 عرضه می‌شود که اجرای PEP 668 را اعمال می‌کند؛ بنابراین اجرای یک pip install anthropic ساده روی مفسر سیستم با خطای error: externally-managed-environment مواجه می‌شود. این خطا نشان‌دهنده عملکرد صحیح سیستم‌عامل است؛ از یک virtualenv استفاده کنید:

sudo apt update && sudo apt install -y python3-venv
sudo python3 -m venv /opt/explain/venv
sudo /opt/explain/venv/bin/pip install anthropic

در محیط سرور نیازی به تشریفات فعال‌سازی (activation) نیست: فراخوانی مستقیم /opt/explain/venv/bin/python همیشه از بسته‌های موجود در venv استفاده می‌کند.

اولین فراخوانی و خواندن صحیح پاسخ

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1000,
    messages=[{"role": "user", "content": "Explain what a systemd unit file is in three sentences."}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

دو مورد در آن دوازده خط، بخش عمده‌ای از مدل ذهنی API را تشکیل می‌دهند. نخست، anthropic.Anthropic() بدون هیچ آرگومانی، کلید را از محیط (environment) می‌خواند؛ هرگز آن را به صورت یک رشته متنی (string literal) ارسال نکنید. دوم، response.content یک لیست از بلوک‌های محتوا است، نه یک رشته. اگر آن را مستقیماً چاپ کنید، خروجی کلاسیکِ تازه‌کارها را دریافت خواهید کرد:

[TextBlock(citations=None, text='A systemd unit file is...', type='text')]

این یک باگ نیست؛ بلکه نمایش (repr) شیء است. پاسخ‌ها می‌توانند شامل چندین نوع بلوک (متن، فراخوانی ابزار، تفکر) باشند، بنابراین باید روی آن‌ها پیمایش (iterate) کنید و پیش از دسترسی به .text، مقدار block.type == "text" را بررسی کنید. این حلقه را از همان روز اول پیاده‌سازی کنید تا یک دسته کامل از سردرگمی‌های مربوط به «چاپ خروجی نامفهوم» هرگز رخ ندهد.

از شناسه مدل دقیق claude-opus-4-8 استفاده کنید. شناسه‌های نسل فعلی فاقد تاریخ هستند؛ در برابر عادت ذهنی (یا پست‌های وبلاگی قدیمی) که به شما می‌گوید یک پسوند تاریخ به آن اضافه کنید، مقاومت کنید؛ این کار منجر به خطای 404 می‌شود که در ادامه به آن پرداخته شده است.

ابزار اصلی: توضیح

در اینجا برنامه کامل، ورودی از stdin، خروجی تشخیص جریان‌یافته (streamed) و مدیریت خطاها آمده است:

#!/usr/bin/env python3
"""explain: pipe an error or log excerpt in, get a diagnosis out."""
import sys
import anthropic

MODEL = "claude-opus-4-8"

def main() -> int:
    text = sys.stdin.read().strip()
    if not text:
        print("usage: journalctl -u nginx -n 50 | explain", file=sys.stderr)
        return 1

    client = anthropic.Anthropic()
    try:
        with client.messages.stream(
            model=MODEL,
            max_tokens=1500,
            system=(
                "You are a senior Linux sysadmin. The user pipes you server "
                "logs or error output. Name the most likely cause outright, "
                "then give the commands to confirm and fix it. Be terse."
            ),
            messages=[{"role": "user", "content": text}],
        ) as stream:
            for chunk in stream.text_stream:
                print(chunk, end="", flush=True)
        print()
    except anthropic.RateLimitError as e:
        retry_after = e.response.headers.get("retry-after", "60")
        print(f"rate limited; retry in {retry_after}s", file=sys.stderr)
        return 2
    except anthropic.APIStatusError as e:
        print(f"API error {e.status_code}: {e.message}", file=sys.stderr)
        return 2
    except anthropic.APIConnectionError:
        print("network error reaching the API", file=sys.stderr)
        return 2
    return 0

if __name__ == "__main__":
    sys.exit(main())

آن را با نام /opt/explain/explain.py ذخیره کنید، سپس یک wrapper اضافه کنید که کلید را برای استفاده تعاملی بارگذاری می‌کند:

sudo tee /usr/local/bin/explain >/dev/null <<'EOF'
#!/bin/sh
set -a; . /etc/claude-explain.env; set +a
exec /opt/explain/venv/bin/python /opt/explain/explain.py "$@"
EOF
sudo chmod 755 /usr/local/bin/explain

(این wrapper باید از طریق sudo اجرا شود یا فایل env باید متعلق به گروهی باشد که کاربر مدیر شما در آن عضو است؛ به‌جای کاهش مجوز فایل به 644، یکی از این دو روش را آگاهانه انتخاب کنید.)

چرا استریمینگ. client.messages.stream توکن‌ها را به محض رسیدن چاپ می‌کند و منتظر تکمیل کل تولید نمی‌ماند؛ این کار از بروز timeout در HTTP برای خروجی‌های طولانی جلوگیری می‌کند. در واقع، SDK برای همین دلیل در فراخوانی‌های غیر استریم، مقادیر بسیار بزرگ max_tokens را رد می‌کند. اگر بعداً به شیء کامل نیاز دارید، stream.get_final_message() را در بلوک with فراخوانی کنید.

چرا این ترتیب استثناها. SDK استثناهای تایپ‌شده را به ترتیب از خاص‌ترین به عمومی‌ترین پرتاب می‌کند: RateLimitError یک خطای 429 است و حاوی هدر retry-after است که مدت زمان انتظار را مشخص می‌کند؛ APIStatusError سایر پاسخ‌های غیر 2xx را پوشش می‌دهد (برای مشکلات سمت سرور، e.status_code >= 500 را بررسی کنید)؛ APIConnectionError به این معنی است که درخواست اصلاً پاسخی دریافت نکرده است. پیش از آنکه یک حلقه retry بسازید، به این نکته توجه کنید: SDK به‌طور پیش‌فرض خطاهای 429 و 5xx را خودش دوباره تلاش می‌کند (به‌طور پیش‌فرض دو بار با backoff نمایی در max_retries کلاینت). زمانی که except شما اجرا می‌شود، تلاش‌های مجدد به پایان رسیده‌اند؛ بنابراین اقدام درست در یک CLI، گزارش خطا و خروج است، نه خوابیدن و ارسال مجدد درخواست.

کنترل هزینه‌ها

این موضوع به دلیل آنکه API هیچ سقف ماهانه‌ای فراتر از آنچه شما پیکربندی می‌کنید ندارد، نیازمند بخش اختصاصی است؛ هر اشتباه در اینجا به‌طور خاموش انباشته می‌شود.

max_tokens سقف هزینه شما برای هر فراخوانی است. توکن‌های خروجی جهت پرهزینه هستند؛ در مدل Opus 4.8، قیمت آن‌ها پنج برابر قیمت ورودی است و max_tokens یک سقف سخت برای تعداد توکن‌هایی است که مدل می‌تواند تولید کند. یک پرامپت خارج از کنترل نمی‌تواند بیش از مقداری که مجاز دانسته‌اید، هزینه خروجی ایجاد کند. آن را متناسب با کار تنظیم کنید: 1,500 توکن برای عیب‌یابی لاگ کافی است؛ یک وظیفه دسته‌بندی به 100 توکن نیاز دارد. اگر پاسخ‌ها با stop_reason: "max_tokens" در میان جمله قطع شدند، یعنی اندازه را خیلی کوچک در نظر گرفته‌اید؛ آن را آگاهانه افزایش دهید و از انتخاب مقادیر بسیار بزرگ به عنوان پیش‌فرض خودداری کنید.

پیش از ارسال، شمارش کنید. ورودی نیز هزینه دارد و لاگ‌ها حجیم هستند. این API یک endpoint شمارش دارد که استفاده از آن رایگان است (این endpoint محدودیت نرخ جداگانه‌ای از ایجاد پیام دارد):

count = client.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": big_log_text}],
)
print(count.input_tokens)

از آن برای جلوگیری از ارسال تصادفی یک لاگ 2 گیگابایتی به ابزار استفاده کنید. برای این کار از tiktoken استفاده نکنید؛ این توکنایزر OpenAI است و توکن‌های Claude را در متن‌های معمولی حدود 15 تا 20 درصد و در کدها حتی بیشتر، کمتر از مقدار واقعی محاسبه می‌کند.

مدل را بر اساس وظیفه انتخاب کنید، نه وفاداری به برند. تا ژوئیه 2026، مدل Opus 4.8 (claude-opus-4-8) با قیمت 5 دلار به ازای هر میلیون توکن ورودی و 25 دلار برای هر میلیون توکن خروجی ارائه می‌شود؛ Haiku 4.5 (claude-haiku-4-5) با قیمت 1 دلار برای ورودی و 5 دلار برای خروجی و با کانتکست 200K در دسترس است؛ Sonnet 5 (claude-sonnet-5) در میانه این دو با قیمت 3 دلار برای ورودی و 15 دلار برای خروجی قرار دارد که تا 31 اوت 2026 با قیمت مقدماتی 2 دلار برای ورودی و 10 دلار برای خروجی عرضه می‌شود. به طور مشخص: یک قطعه لاگ 2,000 توکنی با پاسخ 500 توکنی، در Opus حدود 0.0225 دلار و در Haiku حدود 0.0045 دلار هزینه دارد. زمانی که در حال ارزیابی کیفیت خروجی هستید با Opus شروع کنید، سپس همان پرامپت‌ها را روی Haiku امتحان کنید؛ برای تبدیل‌های ساده و با حجم بالا، تفاوت اغلب غیرقابل تشخیص است در حالی که قیمت آن یک‌پنجم است. پیش از سخت‌کد کردن هر یک از این مقادیر در بودجه، اعداد فعلی را در صفحه قیمت‌گذاری بررسی کنید.

برای هر کاری که عجله‌ای ندارد از Batches استفاده کنید. API مربوط به Batches درخواست‌ها را به صورت غیرهمزمان و با 50 درصد قیمت استاندارد پردازش می‌کند و اکثر دسته‌ها در کمتر از یک ساعت تکمیل می‌شوند. خلاصه‌های شبانه، پر کردن داده‌های قدیمی، دسته‌بندی انبوه و هر کاری که نیازی به انتظار انسان ندارد، در این دسته قرار می‌گیرد.

کش کردن پرامپت برای کانتکست‌های تکراری. اگر هر فراخوانی، همان پرامپت سیستمی بزرگ یا دستورالعمل کاری را دوباره ارسال می‌کند، آن را قابل کش (cacheable) کنید:

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1000,
    system=[{
        "type": "text",
        "text": RUNBOOK_TEXT,  # the same 30K tokens on every call
        "cache_control": {"type": "ephemeral"},
    }],
    messages=[{"role": "user", "content": question}],
)
print(response.usage.cache_read_input_tokens)  # non-zero from the second call on

هزینه نوشتن در کش حدود 1.25 برابر قیمت ورودی و خواندن از کش حدود 0.1 برابر آن است، با TTL پنج دقیقه‌ای؛ بنابراین دومین فراخوانی در این بازه زمانی، هزینه فراخوانی اول را جبران می‌کند. دو نکته وجود دارد: پیشوند کش‌شده باید حداقلِ تعیین‌شده برای هر مدل را رعایت کند (چند هزار توکن در Opus)، بنابراین یک پرامپت سیستمی کوتاه اصلاً کش نمی‌شود. همچنین اگر cache_read_input_tokens در فراخوانی‌های مشابه صفر باقی بماند، یعنی چیزی در پیشوند شما در هر درخواست تغییر می‌کند (معمولاً یک timestamp عامل این اتفاق است).

به یاد داشته باشید چه چیزی به عنوان ورودی محسوب می‌شود. پرامپت‌های سیستمی، تعریف ابزارها و در گفتگوهای چندمرحله‌ای، کل تاریخی که در هر مرحله دوباره ارسال می‌کنید، همگی به عنوان توکن ورودی محاسبه می‌شوند. یک حلقه گفتگو که تاریخچه را کوتاه نمی‌کند، هزینه‌اش به صورت درجه دوم رشد می‌کند. پیش از ساخت هر سیستم گفتگومحور، درک کامل حسابداری توکن‌ها ارزشمند است: نحوه محاسبه واقعی مصرف توکن و صورت‌حساب Claude.

اجرای آن تحت systemd

پاداش رعایت نظم در استفاده از فایل‌های environment: یک تایمر که هر روز صبح خطاهای دیروز را خلاصه می‌کند.

# /etc/systemd/system/log-digest.service
[Unit]
Description=Daily error-log digest via the Claude API

[Service]
Type=oneshot
User=explain
Group=systemd-journal
EnvironmentFile=/etc/claude-explain.env
ExecStart=/bin/sh -c 'journalctl -p err --since yesterday | /opt/explain/venv/bin/python /opt/explain/explain.py >> /var/log/log-digest.txt'

# /etc/systemd/system/log-digest.timer
[Unit]
Description=Run the log digest every morning

[Timer]
OnCalendar=06:15
Persistent=true

[Install]
WantedBy=timers.target

sudo useradd -r -s /usr/sbin/nologin explain
sudo touch /var/log/log-digest.txt && sudo chown explain /var/log/log-digest.txt
sudo systemctl daemon-reload
sudo systemctl enable --now log-digest.timer
sudo systemctl start log-digest.service   # test it once, right now

دقت کنید که EnvironmentFile= چه مزیتی برای شما دارد: systemd فایل متعلق به root با مجوز 600 را پیش از تغییر سطح دسترسی به کاربر غیرمجاز explain می‌خواند؛ بنابراین پردازش متغیر را دریافت می‌کند، در حالی که کاربر نمی‌تواند فایل کلید را بخواند. گروه systemd-journal دسترسی به لاگ‌ها را فراهم می‌کند. با یک systemctl start دستی تست کنید و journalctl -u log-digest.service را بخوانید؛ برای پیدا کردن یک غلط تایپی تا ساعت 06:15 منتظر نمانید. هنگامی که این الگو از یک shell pipeline فراتر رفت، همین رویکردِ قرار دادن کلید در فایل env، مستقیماً در گردش‌کارهای n8n مبتنی بر Claude روی همان سرور قابل استفاده است.

حالت‌های شکست و پیام‌های خطای مربوطه

خطای 401 با وجود کلید معتبر. استثنای دریافتی به این صورت است:

anthropic.AuthenticationError: Error code: 401 - {'type': 'error', 'error': {'type': 'authentication_error', 'message': 'invalid x-api-key'}, 'request_id': 'req_011CSHoEeqs5C35K2UUqR7Fy'}

اگر کلید در shell شما کار می‌کند اما سرویس خطای 401 می‌دهد، یعنی سرویس کلید را دریافت نکرده است. به یاد داشته باشید که systemd فایل .bashrc را نمی‌خواند؛ بررسی کنید که EnvironmentFile= به مسیر درستی اشاره داشته باشد. دلایل دیگر: وجود کوتیشن در فایل env (ANTHROPIC_API_KEY="sk-ant-..."؛ systemd کوتیشن‌ها را حذف می‌کند، اما اگر در shell wrapper خود از . file استفاده کرده باشید، ممکن است کوتیشن‌ها در مقدار باقی بمانند)، وجود فاصله (whitespace) در انتهای رشته، یا کلیدی که هفته گذشته در Console ابطال کرده‌اید.

خطای 404 به دلیل اشتباه تایپی در مدل. رایج‌ترین حالت این است که به شناسه مدل فعلی، پسوند تاریخ اضافه کنید:

anthropic.NotFoundError: Error code: 404 - {'type': 'error', 'error': {'type': 'not_found_error', 'message': 'model: claude-opus-4-8-20260115'}, 'request_id': 'req_011CSJqymAvNw4bT3qmDdMbA'}

شناسه‌های نسل فعلی دقیقاً همان‌طور که نوشته شده‌اند معتبر هستند، مانند claude-opus-4-8، claude-haiku-4-5، claude-sonnet-5. آن‌ها را از مستندات مدل‌ها کپی کنید، هرگز از حفظ یا از آموزش‌های قدیمی استفاده نکنید.

خطای 429 با عنوان rate_limit_error. رشته نوع خطا rate_limit_error است و پاسخ شامل هدر retry-after است که تعداد ثانیه‌های انتظار را مشخص می‌کند. SDK پیش از آنکه شما استثنا را مشاهده کنید، دو بار با مکانیزم backoff تلاش مجدد کرده است؛ بنابراین خطاهای 429 مداوم به این معناست که نرخ درخواست شما واقعاً از سطح (tier) مجاز فراتر رفته است. کارها را به‌صورت دسته‌ای (batch) انجام دهید یا در طول زمان پخش کنید؛ حلقه تلاش مجدد (retry loop) را فشرده‌تر نکنید.

چاپ شدن آبجکت به‌جای متن. خروجی شبیه به [TextBlock(citations=None, text='...', type='text')] است. شما به‌جای پیمایش بلوک‌ها و خواندن .text از بلوک‌هایی که block.type == "text" در آن‌ها برقرار است، response.content را چاپ کرده‌اید. تمام نمونه‌های SDK در بالا این کار را به‌درستی انجام می‌دهند؛ حلقه را کپی کنید.

خطای error: externally-managed-environment. شما دستور pip install را روی پایتون سیستمی Ubuntu 24.04 اجرا کرده‌اید. از venv استفاده کنید؛ هرگز روی سروری که برایتان اهمیت دارد از --break-system-packages استفاده نکنید.

پاسخ‌های ناقص (Truncated). خطای response.stop_reason == "max_tokens" به این معناست که مدل در میانه پردازش به سقف خروجی شما رسیده است. این رفتار طبق طراحی است؛ سقف خروجی را به‌صورت آگاهانه افزایش دهید.

هنگامی که اولین برنامه شما کار کرد، ساخت یک عامل هوش مصنوعی با Claude همان فراخوانی‌های API را به عاملی تبدیل می‌کند که از ابزارها استفاده می‌کند.

FAQ

هزینه استفاده از Claude API برای تست چقدر است؟

برای ابزاری مانند این، هزینه بسیار ناچیز است. تا ژوئیه 2026، مدل Opus 4.8 هزینه‌ای معادل 5 دلار به ازای هر میلیون توکن ورودی و 25 دلار به ازای هر میلیون توکن خروجی دارد؛ بنابراین یک عیب‌یابی لاگ معمولی که شامل چند هزار توکن ورودی و چند صد توکن خروجی باشد، حدود 2 سنت هزینه دارد و در مدل Haiku 4.5 (با قیمت 1 دلار برای ورودی و 5 دلار برای خروجی) این هزینه کمتر از نیم سنت است. هزینه یک ماه گزارش‌گیری روزانه کمتر از قیمت یک فنجان قهوه است. ریسک اصلی در قیمت هر فراخوانی نیست، بلکه در حلقه‌های بی‌نهایت و max_tokens نامحدود است؛ به همین دلیل در این راهنما هر دو مورد به‌طور صریح تنظیم می‌شوند.

آیا Claude API سطح رایگان دارد؟

تا ژوئیه 2026، هیچ سطح رایگان دائمی وجود ندارد. طبق مستندات قیمت‌گذاری Anthropic، کاربران جدید مقدار کمی اعتبار رایگان برای تست API دریافت می‌کنند که یک دوره آزمایشی یک‌باره است و مقدار دقیق آن هنگام ثبت‌نام در Console نمایش داده می‌شود؛ پس از آن باید حساب خود را شارژ کنید. اگر هدف شما به جای کیفیت پیشرو، هزینه نهایی صفر برای هر درخواست است، جایگزین آن میزبانی مدل‌های open-weight با استفاده از Ollama است که در آن هزینه را با مصرف RAM می‌پردازید، نه با توکن.

چگونه کلید API خود را روی سرور امن نگه دارم؟

هرگز آن را در کد، در git، یا خروجی .bashrc قرار ندهید و هرگز در shell تایپ نکنید تا در تاریخچه (history) ذخیره نشود. آن را در فایلی با مالکیت root و دسترسی 600 قرار دهید، برای هر پردازش به‌صورت جداگانه بارگذاری کنید، از یک اسکریپت wrapper برای استفاده تعاملی بهره ببرید، از EnvironmentFile= برای systemd استفاده کنید و برای هر سرور یا پروژه یک کلید مجزا در نظر بگیرید تا در صورت نشت کلید، ابطال آن یک جراحی کوچک باشد، نه یک قطع عضو. اگر کلید به هر طریقی در سایت‌های اشتراک‌گذاری متن یا commitهای git قرار گرفت، بلافاصله آن را در Console باطل کنید؛ حذف commit باعث نشت‌زدایی نمی‌شود.

با کدام مدل Claude شروع کنم؟

زمانی که در حال ارزیابی کیفیت خروجی‌ها برای توسعه هستید، با claude-opus-4-8 شروع کنید؛ چرا که می‌خواهید ایده را با بالاترین کیفیت بسنجید و در حجم کاری سرگرمی، تفاوت هزینه تنها در حد چند سنت است. پس از نهایی شدن prompt، ورودی‌های واقعی خود را با claude-haiku-4-5 دوباره اجرا کنید؛ برای خلاصه‌سازی، دسته‌بندی و اولویت‌بندی لاگ‌ها، این مدل اغلب با یک‌پنجم قیمت، عملکردی مشابه دارد. مهاجرت به Haiku یا Sonnet را بر اساس اندازه‌گیری انجام دهید، نه به‌صورت پیش‌فرض.

#claude-api #python #ai #vps #anthropic