SSD Nodes Learn
Mwongozo Matt ConnorNa Matt Connor · Imeboreshwa 2026-07-24

Jinsi ya kutumia Claude API kwenye VPS

Jifunze kujenga programu ya Python kwenye Ubuntu 24.04 inayotumia Claude API, ikijumuisha streaming, usalama wa key, na udhibiti wa gharama za token.

Unachojenga

Zana ya command-line kwenye VPS mpya ya Ubuntu 24.04. Unapitisha ujumbe wa kosa au sehemu ya log, kisha unapata uchambuzi kwa lugha rahisi: journalctl -u nginx -n 50 | explain. Ni programu ya Python yenye mistari sitini hivi. Inajumuisha mahitaji yote ya programu ya Claude API — funguo (key) iliyohifadhiwa ipasavyo, virtualenv, muundo wa majibu ya SDK, streaming, mnyororo wa exception uliowekwa aina (typed exception chain), na unit ya systemd ili iweze kufanya kazi bila usimamizi wako.

Nimechagua mradi huu kwa makusudi. Mafunzo mengi ya "programu ya kwanza ya API" yanakuambia ujenge chatbot ambayo hutaitumia tena. Programu ya kuelezea log ina faida kwenye seva tangu siku ya kwanza. Pia inakufundisha mambo mawili ambayo wanaoanza hukosea: kusoma kwa usahihi object ya majibu, na kudhibiti gharama. API inatoza kwa token na haina kikomo isipokuwa kile unachoweka, hivyo udhibiti wa gharama ni sehemu ya usanifu hapa. Ni nidhamu inayohitajika pia unapoendelea na kuendesha Claude Code kwenye VPS hii hii ndani ya tmux.

Pata API key kutoka kwenye Console

Ufikiaji wa API unadhibitiwa kwenye Anthropic Console kupitia platform.claude.com — jiunge, kisha tengeneza key chini ya Settings → API Keys (kiungo cha nyaraha kinaelekeza moja kwa platform.claude.com/settings/keys). Key huonyeshwa mara moja tu, huanza na sk-ant-, na haiwezi kupatikana tena — nakili mara moja au futa na utengeneze nyingine.

Kuhusu malipo: kuanzia Julai 2026 hakuna kiwango cha bure cha kudumu kwa ajili ya API. Nyaraka za bei za Anthropic zinaeleza kuwa watumiaji wapya hupata kiasi kidogo cha mikopo ya bure kwa ajili ya majaribio; kiasi kamili ni kile kinachoonyeshwa kwenye Console wakati wa usajili, na baada ya kiasi hicho kuisha, lazima uweke fedha kwenye akaunti ili maombi yafanikiwe. Hii ni tofauti na usajili wa claude.ai — mpango wa Pro au Max haujumuishi mikopo ya API, na API key haikupi ufikiaji wa programu ya chat. Ikiwa unalinganisha usajili na API, mada hiyo ni tofauti: mpango gani wa Claude unaohitaji kweli.

Tengeneza key yenye ukomo wa mradi au seva moja. Key ikivuja — na baada ya muda mrefu, itavuja — utahitaji kuifuta bila kuharibu mifumo mingine unayomiliki.

Usiweke funguo (key) kwenye .bashrc

Hatua ya export ANTHROPIC_API_KEY=sk-ant-... kwenye ~/.bashrc ni ya kurejea (reflexive). Usifanye hivyo. Kuna matatizo matatu tofauti:

  • Kila mchakato (process) huipokea. Variable ya mazingira (environment variable) inayowekwa kwenye login shell yako huenea kwa kila kitu unachoanzisha — programu ya web, ripota wa hitilafu (crash reporter) anayoweka mazingira kwenye ripoti ya hitilafu, au ukurasa wa phpinfo() uliowaziwa. Eneo la hatari la funguo hiyo linakuwa "kila kitu ambacho mtumiaji huyu anakiendesha."
  • Kuandika kwa mkono kunaweka funguo kwenye ~/.bash_history. Ukitekeleza amri ya export kwa mkono mara moja, funguo yako itakaa kwenye faili ya plaintext milele, na itasawazishwa (sync) kwenye kila nakala ya backup ya home directory yako.
  • Haipo wakati systemd inapohitaji. Huduma (services) hazisomi .bashrc yako, hivyo mbinu hii itafeli wakati unapotumia script hiyo kama unit — mara nyingi huleta hitilafu ya 401 saa 6 asubuhi.

Mbinu sahihi kwenye seva ni kutumia faili maalum ya mazingira yenye ruhusa za 600, inayopakuliwa tu na mchakato unaoihitaji:

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 kwenye printf badala ya editor ikiwa unataka kuepuka funguo kwenye faili za swap za editor; kwa njia yoyote, thibitisha kwa ls -l /etc/claude-explain.env kuwa inasoma -rw------- na inamilikiwa na root. Shell za kutoingiza (interactive shells) hupata funguo kwa kila mwito kupitia wrapper (chini), na systemd hupata kupitia EnvironmentFile= — root husoma faili hiyo kabla ya kushusha ruhusa, hivyo mtumiaji wa huduma hahitaji kamwe ruhusa ya kusoma faili hiyo. Funguo haitokezi kwenye kodi, kwenye git, kwenye matokeo ya ps, au kwenye historia ya shell.

Sakinisha SDK kwenye venv

Ubuntu 24.04 inakuja na Python 3.12 inayozingatia PEP 668, hivyo jaribio la pip install anthropic dhidi ya interpreter wa mfumo linafeli kwa error: externally-managed-environment. Hitilafu hiyo ni matokeo ya mfumo kufanya kazi kama ilivyokusudiwa — 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 kuwasha (activate) kwenye seva: kuitumia /opt/explain/venv/bin/python moja kwa moja kila wakati hutumia package za venv.

Wito wa 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 12 ndiyo msingi wa mfumo wa API hii. Kwanza, anthropic.Anthropic() bila argimenti husoma funguo (key) kutoka kwenye mazingira (environment) — usipitishe kama string literal. Pili, response.content ni orodha ya block za maudhui (list of content blocks), siyo string. Ukichapisha (print) moja kwa moja, utapata matokeo ya kawaida ya kuanza:

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

Hili siyo hitilafu; ni repr ya object hiyo. Majibu yanaweza kuwa na aina nyingi za block (text, tool calls, thinking), hivyo unapaswa kutumia loop na kuangalia block.type == "text" kabla ya kugusa .text. Andaa loop hiyo siku ya kwanza ili kuepuka mkanganyiko wa "inachapisha takataka".

Tumia model ID kamili ya claude-opus-4-8. ID za kizazi cha sasa hazina tarehe — usisikilize mazoea (au blog post ya zamani) inayokuambia uongeze kiambishi cha tarehe; itasababisha error ya 404, inayofafanuliwa hapa chini.

Zana halisi: maelezo

Huu hapa ni programu kamili — inapokea stdin, inatoa utambuzi kwa njia ya mtiririko (streamed), na inashughulikia 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())

Iweke kama /opt/explain/explain.py, kisha ongeza wrapper inayopakia ufunguo (key) kwa ajili ya matumizi ya kibaashara (interactive):

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 faili ya mazingira (env file) lazima iwe na kikundi ambacho mtumiaji wako wa admin anacho — chagua njia moja kwa makusudi badala ya kulegeza faili hadi 644.)

Kwa nini kutumia mtiririko (streaming). client.messages.stream huchapisha token zinapofika badala ya kukaa kimya wakati wa kutengeneza data nzima, na iniepuka muda wa mwisho wa HTTP (timeouts) kwenye matokeo marefu — SDK itakataa thamani kubwa za max_tokens kwenye simu zisizo za mtiririko kwa sababu hiyo hiyo. Ukihitaji kitu kilichokusanywa baadaye, piga stream.get_final_message() ndani ya block ya with.

Kwa nini mpangilio huo wa makosa. SDK hutoa makosa yaliyobainishwa (typed exceptions), kuanza na yaliyo mahususi zaidi: RateLimitError ni 429 na ina kichwa cha habari cha retry-after kinachokuambia jinsi ya kusubiri; APIStatusError inashughulikia majibu mengine yasiyo ya 2xx (angalia e.status_code >= 500 kwa matatizo ya upande wa seva); APIConnectionError inamaanisha ombi halikupata jibu kabisa. Na kabla ya kutengeneza loop ya kujaribu tena (retry loop): SDK tayari inajaribu tena makosa ya 429 na 5xx yenyewe, mara mbili kwa kiofisi kwa kutumia exponential backoff (max_retries kwenye client). Wakati except yako inapoendelea, majaribio ya ziada yameshakamilika — hivyo hatua sahihi kwenye CLI ni kutoa taarifa na kutoka, si kusubiri na kushambulia tena.

Udhibiti wa gharama

Sehemu hii ni muhimu kwa sababu API haina kikomo cha kila mwezi zaidi ya kile unachoweka, na kila kosa hapa huongezeka bila kuonekana.

max_tokens ni ukomo wa matumizi yako kwa kila mwito. Tokeni za matokeo (output) ndizo zenye gharama kubwa — kwenye Opus 4.8, ni mara tano ya bei ya pembejeo (input) — na max_tokens ni kikomo kigumu cha idadi ya tokeni ambazo modeli inaweza kuzalisha. Prompt inayozidi mipaka haiwezi kuwa na gharama kubwa zaidi ya matokeo uliyoruhusu. Iweke kulingana na kazi: 1,500 inatosha kwa uchambuzi wa log; kazi ya uainishaji (classification) inahitaji 100. Ikiwa majibu yanasimama katikati ya sentensi kwa stop_reason: "max_tokens", uliweka kikomo kidogo sana — ongeza kikomo hicho kwa makusudi badala ya kutumia viwango vikubwa kama chaguo la kawaida.

Hesabu kabla ya kutuma. Pembejeo pia ina gharama, na log huwa kubwa. API ina njia ya kuhesabu (endpoint) ambayo ni bure kutumia (ina vikomo vyake vya kasi, tofauti na kutengeneza ujumbe):

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

Itumie ili kuzuia kutuma log ya GB 2 kupitia zana hii kwa bahati mbaya. Usitumie tiktoken kwa ajili hii — hiyo ni tokenizer ya OpenAI, na hupunguza idadi ya tokeni za Claude kwa takriban 15–20% kwenye maandishi ya kawaida, na zaidi kwenye kodi.

Chagua modeli kulingana na kazi, si kwa uaminifu. Kuanzia Julai 2026, Opus 4.8 (claude-opus-4-8) inatoza $5 kwa milioni moja ya tokeni za pembejeo na $25 kwa milioni moja ya matokeo; Haiku 4.5 (claude-haiku-4-5) ni $1/$5 ikiwa na muktadha (context) wa 200K; Sonnet 5 (claude-sonnet-5) iko katikati kwa $3/$15, ikiwa na bei ya kuanzia ya $2/$10 hadi Agosti 31, 2026. Kwa vitendo: sehemu ya log ya tokeni 2,000 yenye jibu la tokeni 500 ina gharama ya takriban $0.0225 kwenye Opus na $0.0045 kwenye Haiku. Anza na Opus wakati unapoamua ubora wa matokeo, kisha jaribu prompt zilezile kwenye Haiku — kwa mabadiliko rahisi ya kiasi kikubwa, mara nyingi ni sawa na Opus lakini kwabei ya kumi ya bei hiyo. Hakiki namba za sasa kwenye ukurasa wa bei kabla ya kuweka takwimu hizi kwenye bajeti yako.

Tumia Batches kwa kazi zinazoweza kusubiri. Batches API huchakata maombi bila kusubiri (asynchronously) kwa bei ya 50% ya bei ya kawaida, na batches nyingi hukamilika ndani ya saa moja. Muhtasari wa usiku, kujaza data nyuma (backfills), uainishaji wa jumla — chochote ambacho hakihitaji binadamu kusubiri kiko hapo.

Tumia prompt caching kwa muktadha unaojirudia. Ikiwa kila mwito unatuma tena system prompt kubwa au runbook ileile, iweke iweze kuhifadhiwa (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

Kuandika kwenye cache kuna gharama ya takriban 1.25x ya bei ya pembejeo, kusoma kwenye cache ni takriban 0.1x, kwa muda wa TTL wa dakika 5 — hivyo mwito wa pili ndani ya muda huo tayari unalipia wa kwanza. Changamoto mbili. Prefix iliyohifadhiwa lazima ifuate kiwango cha chini cha kila modeli — tokeni chache za kuanzia kwenye Opus — hivyo system prompt fupi haitahifadhiwa kabisa. Na ikiwa cache_read_input_tokens inabaki kuwa sifuri kwenye maombi yanayofanana, kuna kitu kwenye prefix yako kinachobadilika kila ombi (timestamp ndiyo sababu ya kawaida).

Kumbuka nini kinachohitaji kulipwa kama pembejeo. System prompts, tafsiri za zana (tool definitions), na — katika mazungumzo mengi — historia nzima unayotuma tena kila zamu, yote yanatozwa kama tokeni za pembejeo. Mzunguko wa chat ambao haufuti historia unazidi kuongezeka gharama kwa kasi kubwa. Ni muhimu kuelewa hesabu kamili kabla ya kujenga kitu chochote cha mazungumzo: jinsi matumizi ya tokeni za Claude na malipo yanavyojumlishwa.

Iruni chini ya systemd

Faida ya kutumia mfumo wa environment-file: timer inayokusanya 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 inayomilikiwa na root yenye mode-600 kabla ya kubadilisha mamlaka kwenda kwa mtumiaji asiye na mamlaka explain, hivyo mchakato unapata variable wakati mtumiaji hawezi kusoma faili ya key. Kundi la systemd-journal hutoa ufikiaji wa log. Jaribu kwa kutumia systemctl start ya manual na usome journalctl -u log-digest.service — usisubiri hadi saa 06:15 ili kugundua makosa ya uandishi. Mfumo huu unapozidi uwezo wa shell pipeline, mbinu hiyo hiyo ya key-in-env-file inaweza kutumika kwenye workflows za n8n zinazotumia Claude kwenye mashine hiyo hiyo.

Njia za kushindili, pamoja na maandishi utakayoyaona

401 kwenye funguo inayofanya kazi. Kosa husoma:

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

Ikiwa funguo inafanya kazi kwenye shell yako lakini huduma inatoa 401, huduma haijawahi kuipokea — kumbuka systemd haisomi .bashrc; hakikisha EnvironmentFile= inaelekeza kwenye njia sahihi. Sababu nyingine: alama za nukuu (quotes) zilizowekwa kwenye env file (ANTHROPIC_API_KEY="sk-ant-..." — systemd huondoa alama za nukuu, lakini . file ya shell wrapper yako huziacha kwenye thamani ikiwa uliweka nukuu vibaya), nafasi (whitespace) mwishoni, au funguo uliyofuta kwenye Console wiki iliyopita.

404 kutokana na makosa ya uandishi wa model. Toleo la kawaida zaidi la hili ni kuongeza kiambishi cha tarehe 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'}

ID za kizazi cha sasa ni sahihi kama zilivyoandikwa — claude-opus-4-8, claude-haiku-4-5, claude-sonnet-5. Nakili kutoka kwenye hati ya maelezo ya model, usitumie kumbukumbu au mwongozo wa zamani.

429 rate_limit_error. Aina ya maandishi ya kosa ni rate_limit_error na jibu hubeba kichwa cha habari (header) cha retry-after chenye sekunde za kusubiri. SDK tayari imejaribu tena mara mbili kwa kutumia backoff kabla ya kuona kosa, hivyo 429 zinazojirudia zinamaanisha kiwango chako cha kudumu kinazidi kiwango chako — gawanya kazi kwa awamu au itenganishe, usikazie zaidi mzunguko wa kujaribu tena (retry loop).

Inachapisha object, siyo maandishi. Matokeo yanaonekana kama [TextBlock(citations=None, text='...', type='text')]. Ulichapisha response.content badala ya kupitia blocks na kusoma .text kutoka kwenye zile ambazo block.type == "text". Kila mfano wa SDK hapo juu unafanya hivyo kwa usahihi; nakili mzunguko (loop) huo.

error: externally-managed-environment. Ulitekeleza pip install dhidi ya Python ya mfumo ya Ubuntu 24.04. Tumia venv — usitumie --break-system-packages kwenye seva muhimu.

Majibu yaliyokatwa. response.stop_reason == "max_tokens" inamaanisha model imefika kikomo cha matokeo (output cap) katikati ya kufikiri. Inafanya kazi kama ilivyokusudiwa; ongeza kikomo hicho kwa makusudi.

Baada ya programu yako ya kwanza kufanya kazi, ujenzi wa AI agent kwa kutumia Claude unageuza mwito huo huo wa API kuwa agent inayotumia zana (tools).

FAQ

Claude API inagharimu kiasi gani kujaribu?

Ni kiasi kidogo sana kwa zana kama hii. Kufikia Julai 2026, Opus 4.8 inagharimu $5 kwa milioni moja ya input tokens na $25 kwa milioni moja ya output. Kwa mfano, uchunguzi wa log kawaida — maelfu machache ya tokens ndani, mamia machache nje — ni takriban senti mbili, na kwenye Haiku 4.5 ($1/$5) ni chini ya senti nusu. Mwezi mzima wa muhtasari wa kila siku gharama yake ni chini ya bei ya kahimbi. Hatari si bei ya kila mwito; ni loops zisizo na kikomo na max_tokens zisizo na kikomo, ndiyo maana zote mbili huwekwa wazi katika mwongozo huu.

Je, kuna tier ya bure kwa Claude API?

Hakuna tier ya bure inayodumu kufikia Julai 2026. Nyaraka za bei za Anthropic zinaeleza kuwa watumiaji wapya hupata kiasi kidogo cha credit za bure ili kujaribu API — jaribio la mara moja tu, ambapo kiasi kamili huonyeshwa kwenye Console wakati wa usajili — baada ya hapo unapaswa kuweka pesa kwenye akaunti. Ikiwa lengo lako ni gharama sifuri kwa kila ombi badala ya ubora wa juu, mbadala ni kujihostia open-weight model kwa kutumia Ollama na kulipia kwa RAM badala ya tokens.

Nitahifadhaje API key yangu salama kwenye server?

Usiiweke kamwe kwenye code, kamwe kwenye git, kamwe usitoe nje kutoka .bashrc, na usiiandike kamwe kwenye shell ambapo history itaikumbuka. Iweke kwenye faili inayomilikiwa na root ikiwa na ruhusa za 600, iweke kwa kila process — script ya wrapper kwa matumizi ya interactive, na EnvironmentFile= kwa systemd — na uweke key moja kwa kila server au mradi ili kufuta key iliyovuja iwe rahisi kama upasuaji, siyo kama kukata kiungo. Ikiwa key itatokea kwenye tovuti ya paste au git commit, ifute kwenye Console mara moja; kufuta commit hakiondoi uvujaji huo.

Ni modeli gani ya Claude nianze nayo?

Anza na claude-opus-4-8 wakati unapoendelea kutathmini ikiwa matokeo ni mazuri ya kutosha kujenga juu yake — unahitaji kuipima idea kwa ubora kamili, na kwa matumizi madogo tofauti ya gharama ni senti tu. Baada ya prompt kuwekwa sawa, rudia input zako halisi kwenye claude-haiku-4-5; kwa muhtasari, uainishaji, na uchunguzi wa log, mara nyingi ni nzuri sawa kwa bei ya kumi ya bei ya awali. Hamia kwenye Haiku au Sonnet kwa kutumia vipimo, siyo kwa chaguo la kawaida.

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