Mwongozo

Na Matt Connor 2026-07-15 · Imeboreshwa 2026-08-03

Mafunzo ya Claude API: Programu ya Kwanza kwenye VPS

Q: Ninawezaje kulinda API key yangu kwenye seva?

Usiiweke kamwe kwenye code, git, au kui-export kutoka .bashrc. Pia usiiandike kwenye shell ambayo history yake itaihifadhi. Iweke kwenye faili inayomilikiwa na root yenye permissions za 600. Ipakie kwa kila process. Tumia wrapper script kwa matumizi ya kuingiliana, na EnvironmentFile= kwa systemd. Tumia key moja kwa kila seva au project ili uweze kubatilisha key iliyovuja bila kuathiri nyingine. Ikiwa key itawahi kuwekwa kwenye paste site au git commit, ibatilisha mara moja kwenye Console. Kufuta commit hakutaondoa uvujaji huo.

Q: Nianze na Claude model ipi?

Anza na claude-opus-4-8 unapopima kama outputs zake ni nzuri vya kutosha kujengea mfumo. Hii hukuwezesha kutathmini wazo hilo kwa ubora kamili. Kwa matumizi ya kiwango cha hobby, tofauti ya gharama ni senti chache. Baada ya prompt kukamilika, endesha tena input zako halisi kwenye claude-haiku-4-5. Kwa summarization, classification na log triage, mara nyingi huwa na ubora unaokaribiana kwa bei ya moja ya tano. Chagua Haiku au Sonnet kulingana na vipimo, si kwa default.

Jenga kichanganua logi cha Python kwenye Ubuntu 24.04 kwa Claude API, ukiweka key salama, streaming, exceptions zenye aina na udhibiti halisi wa gharama.

Unachojenga

Zana ya mstari wa amri kwenye VPS mpya ya Ubuntu 24.04 ambayo unaingiza ujumbe wa hitilafu au kipande cha logi kupitia pipe na kupata utambuzi wa wazi kwa Kiingereza: journalctl -u nginx -n 50 | explain. Inaweza kuwa na takribani mistari sitini ya Python, na inakupitisha kwenye vipengele vyote muhimu vya programu halisi ya Claude API: key iliyohifadhiwa kwa usahihi, virtualenv, miundo ya majibu ya SDK, streaming, mfululizo wa exceptions zenye aina maalumu, na systemd unit ili iendeshe bila kuianzisha wewe.

Nilichagua mradi huu kimakusudi. Tutorials nyingi za "programu ya kwanza ya API" zinakujengea chatbot ambayo hutafungua tena. Kichanganua logi huwa na manufaa kwenye seva tangu siku ya kwanza, na kinakulazimisha kushughulikia mambo mawili ambayo wanaoanza hukosea: kusoma response object kwa usahihi na kudhibiti matumizi. API hutoza kwa kila token bila kikomo kingine isipokuwa vile unavyoweka, kwa hiyo udhibiti wa gharama ni sehemu ya usanifu hapa, si jambo la kushughulikiwa baadaye. Hii ni nidhamu ileile inayohitajika unapofikia kuendesha Claude Code kwenye VPS hii hii ndani ya tmux.

Pata ufunguo wa API kutoka Console

Ufikiaji wa API unasimamiwa katika Anthropic Console kwenye platform.claude.com. Jisajili, kisha uunde ufunguo chini ya Settings → API Keys (kiungo cha nyaraka kinaenda moja kwa moja kwenye platform.claude.com/settings/keys). Ufunguo huonyeshwa mara moja tu, huanza na sk-ant-, na hauwezi kupatikana tena. Unakili mara moja au uufute kisha uunde mwingine.

Kuhusu gharama: kufikia Julai 2026 hakuna kiwango cha bure kinachoendelea kwa API. Nyaraka za bei za Anthropic zinasema kuwa watumiaji wapya hupokea kiasi kidogo cha credits za bure za majaribio. Kiasi halisi ni kile kinachoonyeshwa na Console wakati wa kujisajili. Credits zikisha, unaweka fedha kwenye akaunti kabla ya maombi kufanikiwa. Hii ni tofauti na subscription ya claude.ai. Mpango wa Pro au Max haujumuishi credit ya API, na API key haikupi chat app. Ikiwa unalinganisha subscription na API, uamuzi huo ni mada tofauti: mpango wa Claude unaohitaji hasa.

Unda ufunguo unaohusishwa na project au server moja. Ufunguo ukivuja, na baada ya muda wa kutosha kuna uwezekano wa kuvuja, utahitaji kuufuta bila kuvuruga rasilimali zako nyingine.

Weka key mbali na .bashrc

Hatua ya kawaida ya haraka ni export ANTHROPIC_API_KEY=sk-ant-... katika ~/.bashrc. Usifanye hivyo. Kuna matatizo matatu tofauti:

Kila mchakato huirithi. Environment variable iliyotangazwa kwenye login shell yako husambaa kwa kila kitu unachoanzisha: web app, crash reporter ambayo huhifadhi environment yake kwenye bug report, na ukurasa wa phpinfo() ambao mtu aliacha ukiwa umewezeshwa. Eneo la key kuonekana linakuwa “kila kitu ambacho mtumiaji huyu huendesha.”
Kuingiza key huifanya ihifadhiwe katika ~/.bash_history. Ukiendesha export kwa mkono mara moja, key yako inakaa kwenye faili ya maandishi wazi bila kikomo, na husawazishwa kwenye kila backup ya home directory yako.
Haipo systemd inapoiitaji. Services hazisomi .bashrc yako, kwa hiyo muundo huu hushindwa hasa unapobadilisha script kuwa unit, kwa kawaida ukapata 401 isiyoeleweka saa 6 asubuhi.

Muundo sahihi kwenye seva ni environment file maalumu yenye permissions za 600, inayopakiwa na mchakato unaoihitaji pekee:

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

Tumia tee kutoka kwa printf badala ya editor ikiwa unataka kuzuia key isiingie kwenye editor swap files. Kwa vyovyote vile, thibitisha kwa ls -l /etc/claude-explain.env kwamba inasoma -rw------- na kwamba inamilikiwa na root. Interactive shells hupata key kwa kila invocation kupitia wrapper (hapo chini), na systemd huipata kupitia EnvironmentFile=. root husoma faili kabla ya kuacha privileges, kwa hiyo service user haihitaji read access yake. Key haionekani kamwe kwenye code, git, ps output, au shell history.

Sakinisha SDK katika venv

Ubuntu 24.04 inasafirisha Python 3.12 ikiwa na utekelezaji wa PEP 668, kwa hiyo pip install anthropic inayotumia system interpreter moja kwa moja inashindwa kwa error: externally-managed-environment. Hitilafu hiyo inaonyesha kuwa OS inafanya kazi iliyokusudiwa; tumia 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

Hakuna haja ya hatua za activation kwenye server: kuita /opt/explain/venv/bin/python moja kwa moja hutumia packages za venv.

Simu ya kwanza na kusoma jibu kwa usahihi

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)

Mambo mawili katika mistari hiyo kumi na miwili yanaeleza sehemu kubwa ya muundo wa kiakili wa API. Kwanza, anthropic.Anthropic() bila hoja husoma key kutoka kwenye environment; usiwahi kuipitisha kama string literal. Pili, response.content ni orodha ya content blocks, si string. Ukiichapisha moja kwa moja, utapata matokeo haya ya kawaida kwa anayeanza:

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

Hilo si hitilafu; ni repr ya object. Majibu yanaweza kuwa na aina nyingi za blocks, kama text, tool calls na thinking. Kwa hiyo, pitia kila block na ukague block.type == "text" kabla ya kufikia .text. Weka loop hiyo tangu siku ya kwanza. Hivyo utaepuka kabisa mkanganyiko wa aina ya “inachapisha takataka”.

Tumia model ID halisi claude-opus-4-8. IDs za kizazi cha sasa hazina tarehe. Usifuate mazoea ya zamani au maelekezo ya blogu ya zamani ya kuongeza date suffix. Kufanya hivyo husababisha 404, kama ilivyoelezwa hapa chini.

Zana halisi: maelezo

Huu ndio programu kamili: hupokea data kupitia stdin, hutoa utambuzi kwa mtiririko, na hushughulikia makosa:

#!/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())

Ihifadhi kama /opt/explain/explain.py, kisha ongeza wrapper inayopakia key kwa matumizi ya mwingiliano:

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 inahitaji kuendeshwa kupitia sudo, au env file iwe na group ambayo mtumiaji wako wa usimamizi ni mwanachama wake. Chagua mojawapo kwa makusudi badala ya kulegeza ruhusa za file hadi 644.)

Kwa nini utiririshaji. client.messages.stream huchapisha tokens zinapowasili badala ya kukaa kimya hadi generation nzima ikamilike. Pia huepuka HTTP timeouts kwenye outputs ndefu. SDK itakataa values kubwa sana za max_tokens kwenye calls zisizo za streaming kwa sababu hiyo hiyo. Ikiwa unahitaji object iliyokusanywa baadaye, ita stream.get_final_message() ndani ya block ya with.

Kwa nini mpangilio huo wa exceptions. SDK huinua typed exceptions kwa mpangilio wa kuanzia maalum zaidi: RateLimitError ni 429 na hubeba header ya retry-after inayokuambia muda wa kusubiri; APIStatusError hushughulikia responses nyingine zisizo za 2xx (angalia e.status_code >= 500 kwa matatizo upande wa server); APIConnectionError humaanisha kuwa request haikupokea response kabisa. Kabla hujaunda retry loop, kumbuka: SDK tayari hujaribu tena errors za 429 na 5xx yenyewe, mara mbili kwa default na exponential backoff (max_retries kwenye client). Kufikia wakati except inaendeshwa, majaribio ya retry huwa yamekwisha. Kwa hiyo, kwenye CLI, hatua sahihi ni kuripoti na kutoka, si kusubiri kisha kutuma maombi tena kwa nguvu.

Udhibiti wa gharama

Hii inahitaji sehemu yake kwa sababu API haina kikomo cha kila mwezi kilichojengwa ndani, isipokuwa kile unachosanidi, na kila kosa hapa huongeza gharama bila kuonekana.

max_tokens ni kiwango cha juu cha matumizi kwa kila ombi. Output tokens ndizo zenye gharama kubwa zaidi. Kwenye Opus 4.8, bei yake ni mara tano ya input tokens, na max_tokens ni kikomo kisichoweza kuzidi cha idadi ya tokeni ambazo model inaweza kutoa. Prompt inayozunguka bila kikomo haiwezi kugharimu output inayozidi kiasi ulichoruhusu. Weka kikomo kulingana na kazi: 1,500 zinatosha kwa uchunguzi wa log; kazi ya uainishaji inahitaji 100. Majibu yakikatika katikati ya sentensi yakiwa na stop_reason: "max_tokens", uliweka kikomo kidogo sana. Kiongeze kwa makusudi badala ya kuweka kikomo kikubwa bila sababu.

Hesabu kabla ya kutuma. Input pia ina gharama, na log huwa kubwa. API ina endpoint ya kuhesabu inayoweza kutumiwa bila malipo. Ina rate limits zake, tofauti na uundaji wa ujumbe:

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

Itumie kuzuia kutuma log ya 2 GB kupitia tool bila kukusudia. Usitumie tiktoken kwa kazi hii. Hiyo ni tokenizer ya OpenAI, na kwa kawaida huhesabu tokeni za Claude chini kwa takriban 15–20% kwenye maandishi ya kawaida, na tofauti huwa kubwa zaidi kwenye code.

Chagua model kulingana na kazi, si kwa uaminifu kwa model moja. Kufikia July 2026, Opus 4.8 (claude-opus-4-8) hugharimu $5 kwa kila tokeni za input milioni moja na $25 kwa kila tokeni za output milioni moja. Haiku 4.5 (claude-haiku-4-5) hugharimu $1/$5 na ina context ya 200K. Sonnet 5 (claude-sonnet-5) iko katikati kwa $3/$15, ikiwa na bei ya utangulizi ya $2/$10 hadi August 31, 2026. Kwa mfano, sehemu ya log yenye tokeni 2,000 na jibu la tokeni 500 hugharimu takriban $0.0225 kwenye Opus na $0.0045 kwenye Haiku. Anza na Opus unapopima ubora wa majibu. Kisha jaribu prompt zilezile kwenye Haiku. Kwa transformations rahisi zenye matumizi mengi, mara nyingi tofauti yake haionekani, huku gharama ikiwa moja ya tano. Thibitisha bei za sasa kwenye ukurasa wa pricing kabla ya kuweka nambari hizi moja kwa moja kwenye bajeti.

Tumia Batches kwa kazi zinazoweza kusubiri. Batches API huchakata maombi asynchronously kwa 50% ya bei za kawaida, na batches nyingi hukamilika ndani ya saa moja. Digests za kila usiku, backfills, uainishaji wa kiasi kikubwa, na kazi yoyote ambayo haihitaji mtu kusubiri inafaa kuwekwa hapo.

Tumia prompt caching kwa context inayorudiwa. Ikiwa kila ombi linatuma tena system prompt au runbook ileile yenye ukubwa mkubwa, iweke iweze kuwekwa kwenye cache:

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

Kuandika cache hugharimu takriban mara 1.25 ya bei ya input, na kusoma cache hugharimu takriban mara 0.1 ya bei hiyo, kwa TTL ya dakika 5. Kwa hiyo, ombi la pili ndani ya muda huo tayari hulipia gharama ya kwanza. Kuna masharti mawili. Prefix iliyowekwa kwenye cache lazima ifikie kiwango cha chini kinachotegemea model, ambacho ni tokeni elfu kadhaa kwenye Opus. Kwa hiyo, system prompt fupi inaweza kutowekwa kwenye cache kabisa bila ujumbe wa wazi. Pia, ikiwa cache_read_input_tokens inabaki kuwa sifuri kwenye maombi yanayofanana, kuna sehemu ya prefix inayobadilika kila ombi. Timestamp ndiyo sababu ya kawaida.

Kumbuka vitu vinavyohesabiwa kama input. System prompts, tool definitions, na katika mazungumzo ya hatua nyingi, historia yote unayotuma tena kila hatua, vyote hutozwa kama input tokens. Chat loop isiyopunguza historia huongeza gharama kwa kasi ya quadratic. Ni muhimu kuelewa hesabu kamili kabla ya kujenga mfumo wa mazungumzo: jinsi matumizi ya tokeni na billing ya Claude yanavyohesabiwa.

Iendeshe chini ya systemd

Faida ya nidhamu ya environment file ni timer inayofupisha makosa ya jana kila asubuhi.

# /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

Zingatia faida ya EnvironmentFile=: systemd husoma faili lenye umiliki wa root na mode-600 kabla ya kumhamishia mchakato kwa mtumiaji asiye na mamlaka explain. Kwa hiyo, mchakato hupata variable, huku mtumiaji huyo asiweze kusoma faili la key. Group ya systemd-journal hutoa ruhusa ya kufikia logs. Fanya jaribio kwa systemctl start ya mwongozo na usome journalctl -u log-digest.service; usisubiri 06:15 ndipo ugundue typo. Muundo huu ukizidi uwezo wa shell pipeline, mbinu hiyo hiyo ya kuweka key kwenye environment file inaweza kutumika moja kwa moja katika workflows za n8n zinazoendeshwa na Claude kwenye box hiyo hiyo.

Njia za kushindwa, pamoja na mistari utakayoona

401 kwa key inayofanya kazi. Exception inaonyesha:

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

Ikiwa key inafanya kazi kwenye shell yako lakini service inarudisha 401, service haikuwahi kuipokea. Kumbuka kwamba systemd haisomi .bashrc; hakikisha EnvironmentFile= inaelekeza kwenye path sahihi. Sababu nyingine ni quotes zilizobandikwa kwenye env file (ANTHROPIC_API_KEY="sk-ant-...", systemd huondoa quotes hizo, lakini . file ya shell wrapper yako huzihifadhi ndani ya value ikiwa uliweka quotes kwa njia isiyo sahihi), whitespace iliyo mwishoni, au key uliyo-revoke kwenye Console wiki iliyopita.

404 kutokana na typo ya model. Toleo linalotokea mara nyingi zaidi ni kuongeza date suffix kwenye model ID ya sasa:

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

IDs za current-generation lazima ziandikwe sawasawa, claude-opus-4-8, claude-haiku-4-5, claude-sonnet-5. Zikopi kutoka kwenye documentation ya models, kamwe usizikumbuke kutoka kichwani au kwenye tutorial ya zamani.

429 rate_limit_error. String ya aina ya error ni rate_limit_error, na response hubeba header ya retry-after yenye idadi ya sekunde za kusubiri. SDK tayari imejaribu tena mara mbili kwa backoff kabla hujaona exception. Kwa hiyo, 429 zinazoendelea humaanisha sustained rate yako inazidi tier yako. Panga kazi kwa batches au zisambaze kwa muda; usipunguze muda wa retry loop.

Inachapisha object badala ya text. Output inaonekana kama [TextBlock(citations=None, text='...', type='text')]. Ulichapisha response.content badala ya kuzunguka kwenye blocks na kusoma .text kutoka kwenye zile ambazo block.type == "text". Kila mfano wa SDK hapo juu hufanya hivyo kwa usahihi; kopi loop hiyo.

error: externally-managed-environment. Uliendesha pip install dhidi ya system Python ya Ubuntu 24.04. Tumia venv; kamwe usitumie --break-system-packages kwenye server unayoithamini.

Majibu yaliyokatwa. response.stop_reason == "max_tokens" inamaanisha model ilifikia kikomo chako cha output katikati ya wazo. Hii inafanya kazi kulingana na muundo uliokusudiwa; ongeza kikomo kwa makusudi.

Baada ya app yako ya kwanza kufanya kazi, kujenga AI agent kwa kutumia Claude hubadilisha API calls hizo hizo kuwa agent inayotumia tools.

FAQ

Inagharimu kiasi gani kujaribu Claude API?

Kwa kweli, ni gharama ndogo sana kwa zana kama hii. Kufikia July 2026, Opus 4.8 inagharimu $5 kwa kila token milioni moja za input na $25 kwa kila token milioni moja za output. Kwa hiyo, uchanganuzi wa kawaida wa logi, wenye token elfu chache za input na mia chache za output, hugharimu takribani senti mbili. Kwa Haiku 4.5 ($1/$5), gharama huwa chini ya nusu senti. Digesti za kila siku kwa mwezi hugharimu chini ya kahawa moja. Hatari si gharama ya kila ombi, bali loops zisizo na kikomo na max_tokens isiyo na kikomo. Ndiyo sababu vyote viwili huwekwa wazi katika mwongozo huu.

Je, kuna kiwango cha bure cha Claude API?

Hakuna kiwango cha bure kinachoendelea kufikia July 2026. Nyaraka za bei za Anthropic zinasema kuwa watumiaji wapya hupokea kiasi kidogo cha credits za bure za kuijaribu API. Hii ni trial ya mara moja, na kiasi halisi huonyeshwa kwenye Console wakati wa kujisajili. Baada ya hapo, unaweka fedha kwenye akaunti. Ikiwa lengo lako ni kutokuwa na gharama ya ziada kwa kila ombi badala ya kupata ubora wa juu zaidi, unaweza kujihudumia model ya open-weight kwa Ollama na kutumia RAM badala ya tokeni.

Ninawezaje kulinda API key yangu kwenye seva?

Usiiweke kamwe kwenye code, git, au kui-export kutoka .bashrc. Pia usiiandike kwenye shell ambayo history yake itaihifadhi. Iweke kwenye faili inayomilikiwa na root yenye permissions za 600. Ipakie kwa kila process. Tumia wrapper script kwa matumizi ya kuingiliana, na EnvironmentFile= kwa systemd. Tumia key moja kwa kila seva au project ili uweze kubatilisha key iliyovuja bila kuathiri nyingine. Ikiwa key itawahi kuwekwa kwenye paste site au git commit, ibatilisha mara moja kwenye Console. Kufuta commit hakutaondoa uvujaji huo.

Nianze na Claude model ipi?

Anza na claude-opus-4-8 unapopima kama outputs zake ni nzuri vya kutosha kujengea mfumo. Hii hukuwezesha kutathmini wazo hilo kwa ubora kamili. Kwa matumizi ya kiwango cha hobby, tofauti ya gharama ni senti chache. Baada ya prompt kukamilika, endesha tena input zako halisi kwenye claude-haiku-4-5. Kwa summarization, classification na log triage, mara nyingi huwa na ubora unaokaribiana kwa bei ya moja ya tano. Chagua Haiku au Sonnet kulingana na vipimo, si kwa default.

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