کار با API و کلیدها در هوش مصنوعی

بیشتر ابزارها و ایجنت‌های هوش مصنوعی امروزی بر پایه‌ی ارسال درخواست به رابط‌های برنامه‌نویسی کاربردی (API) و دریافت پاسخ کار می‌کنند. تسلط بر نحوه‌ی کارکرد این سرویس‌ها، شناخت ساختار درخواست‌ها و روش‌های ایمن نگه داشتن کلیدهای دسترسی، اولین گام ضروری برای توسعه‌ی نرم‌افزارهای مبتنی بر مدل‌های زبانی بزرگ است.

در کار با سرویس‌دهندگانی مانند OpenAI یا Anthropic، پرداخت مستقیم با کارت‌های بانکی ایرانی امکان‌پذیر نیست و برخی سرویس‌ها نیز دسترسی از IP ایران را محدود کرده‌اند؛ بنابراین شناخت ساختار خام فراخوانی‌های HTTP اهمیت دوچندان پیدا می‌کند. شما می‌توانید با درک عمیق این الگوها، بدون وابستگی کامل به یک SDK خاص، درخواست‌های خود را در صورت نیاز به سمت گیت‌وی‌های واسط یا سازگار بازنویسی کنید.

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

اهداف یادگیری

• ذخیره‌ی امن کلیدهای API با استفاده از متغیرهای محیطی (environment variables) و فایل‌های .env
• فراخوانی API یک LLM هم با SDK پایتونِ Anthropic و هم با HTTP خام
• مقایسه‌ی ساختار درخواست و پاسخ در روش مبتنی بر SDK و HTTP خام برای خطایابی بهتر
• شناسایی و مدیریت خطاهای رایج API از جمله خطاهای احراز هویت و محدودیت نرخ درخواست (rate limit)

صورت مسئله

از فاز 11 به بعد، APIهای مدل‌های زبانی (Anthropic، OpenAI و Google) را فراخوانی خواهید کرد. در فازهای 13 تا 16 هم ایجنت‌هایی می‌سازید که این APIها را درون حلقه به کار می‌گیرند. باید بدانید کلیدهای API چطور کار می‌کنند، چگونه آن‌ها را امن نگه دارید و چطور نخستین فراخوانی API خود را انجام دهید.

مفهوم اصلی

هر فراخوانی API از این بخش‌ها تشکیل می‌شود:

1. یک اندپوینت (URL)
2. یک کلید API (برای احراز هویت)
3. بدنه‌ی درخواست (Request body): آنچه می‌خواهید
4. بدنه‌ی پاسخ (Response body): آنچه در جواب می‌گیرید

پیاده‌سازی

گام 1: ذخیره‌ی امن کلیدهای API

هرگز کلیدهای API را داخل کد نگذارید؛ همیشه از متغیرهای محیطی استفاده کنید.

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

یا از یک فایل .env کمک بگیرید (و حتماً آن را به .gitignore اضافه کنید):

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

گام 2: نخستین فراخوانی API (پایتون)

import os

import anthropic

client = anthropic.Anthropic()

MODEL = os.environ.get("LLM_MODEL", "claude-sonnet-5")

response = client.messages.create(
    model=MODEL,
    max_tokens=256,
    messages=[{"role": "user", "content": "What is a neural network in one sentence?"}]
)

print(response.content[0].text)

متغیر LLM_MODEL شناسه‌ی مدل Anthropic را مشخص می‌کند و مقدار پیش‌فرض آن، نام مستعار بدون تاریخ Sonnet است. سایر ارائه‌دهندگان (OpenAI، Google و دیگران) هم از همین الگوی «کلید به‌اضافه‌ی شناسه‌ی مدل» پیروی می‌کنند؛ اما هرکدام SDK، اندپوینت و اسکیما یا ساختار درخواست و پاسخ مخصوص خود را دارند.

گام 3: نخستین فراخوانی API (تایپ‌اسکریپت)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const MODEL = process.env.LLM_MODEL ?? "claude-sonnet-5";

const response = await client.messages.create({
  model: MODEL,
  max_tokens: 256,
  messages: [{ role: "user", content: "What is a neural network in one sentence?" }],
});

console.log(response.content[0].text);

گام 4: HTTP خام (بدون SDK)

import os
import urllib.request
import json

url = "https://api.anthropic.com/v1/messages"
headers = {
    "Content-Type": "application/json",
    "x-api-key": os.environ["ANTHROPIC_API_KEY"],
    "anthropic-version": "2023-06-01",
}
body = json.dumps({
    "model": os.environ.get("LLM_MODEL", "claude-sonnet-5"),
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "What is a neural network in one sentence?"}],
}).encode()

req = urllib.request.Request(url, data=body, headers=headers, method="POST")
with urllib.request.urlopen(req) as resp:
    result = json.loads(resp.read())
    print(result["content"][0]["text"])

این در واقع همان کاری است که SDKها در پسِ صحنه انجام می‌دهند. درک نحوه‌ی ارسال درخواست خام HTTP هنگام خطایابی حسابی به کارتان می‌آید.

استفاده از ابزارها

برای این دوره:

همین الان به همه‌ی آن‌ها نیاز ندارید. هر زمان که درسی آن را خواست، راه‌اندازی‌اش کنید.

تحویل پروژه

خروجی این درس:

• outputs/prompt-api-troubleshooter.md - عیب‌یابی خطاهای رایج API

تمرین‌ها

1. یک کلید API از Anthropic بگیرید و نخستین فراخوانی API خود را انجام دهید.
2. نسخه‌ی خام HTTP را امتحان کنید و فرمت پاسخ آن را با نسخه‌ی SDK مقایسه کنید.
3. عمداً از یک کلید API اشتباه استفاده کنید و پیام خطا را بخوانید.

راهنمایی‌ها

تمرین 1. داخل کنسول Anthropic یک کلید بسازید، آن را مطابق آموزش در ANTHROPIC_API_KEY قرار دهید و فایل code/first_api_call.py را اجرا کنید. فراخوانی زمانی درست کار کرده است که اسکریپت پاسخ مدل را بدون هیچ خطایی چاپ کند.

تمرین 2. هر دو تابع در code/first_api_call.py فقط متن و تعداد توکن‌ها را چاپ می‌کنند. دستور print(response) را در call_with_sdk() و print(result) را در call_raw_http() بگذارید، سپس اسکریپت را اجرا کنید تا کل هر دو پاسخ را ببینید. نام فیلدها را مقایسه کنید: JSON خام همان فیلدهای content، usage و stop_reason را دارد که SDK آن‌ها را به ویژگی‌های شیء (object attributes) تبدیل می‌کند.

تمرین 3. مقدار ANTHROPIC_API_KEY را فقط در یک ترمینال روی یک مقدار ساختگی تنظیم کنید و اسکریپت را دوباره اجرا کنید. کد وضعیت HTTP و نوع خطا را در خروجی پیدا کنید؛ شکست در احراز هویت کد وضعیت 401 برمی‌گرداند.

اصطلاحات کلیدی