Guna Ollama dengan Ejen Pengekodan Anda

Sambungan yang anda gunakan

Anda boleh menggunakan Ollama dengan ejen pengekodan anda. Sambungan ini lebih ringkas daripada jangkaan ramai. Anda hanya perlu mengubah satu URL asas dan memilih satu nama model. Medan kunci API masih memerlukan nilai, tetapi pelayan setempat mengabaikannya. Oleh itu, apa-apa rentetan boleh digunakan.

Ollama mendengar pada port 11434 dan menyediakan dua bentuk permintaan pada masa yang sama. /v1/chat/completions ialah bentuk yang serasi dengan OpenAI. Dokumentasi Ollama menyatakan bahawa kunci dalam bentuk ini diperlukan tetapi diabaikan. /v1/messages ialah bentuk yang serasi dengan Anthropic, iaitu bentuk yang digunakan oleh Claude Code. Ejen anda sudah menyokong salah satu daripada kedua-duanya. Oleh itu, tiada perkara lain perlu diubah.

Bahagian ini mengambil masa lima minit. Sama ada hasilnya boleh digunakan bergantung pada dua tetapan yang hampir tiada siapa ubah, iaitu panjang konteks dan keep-alive, serta pemberian tugasan yang sesuai dengan keupayaan model. Setiap tetapan akan dibincangkan dalam bahagiannya sendiri. Had sebenar akan diterangkan pada bahagian akhir.

Ejen pengekodan yang menerima URL asas setempat

Ujian ini hanya melibatkan satu soalan: adakah alat tersebut menyediakan tetapan URL asas? Jika ya, alat itu boleh berkomunikasi dengan pelayan anda.

Ollama menerbitkan halaman integrasi untuk Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, JetBrains IDEs dan VS Code. Aider mendokumenkan sokongan Ollama sendiri secara berasingan. Ini merangkumi kebanyakan alat yang dimaksudkan sebagai ejen pengekodan pada Ogos 2026. Alat-alat ini tidak semuanya menggunakan format yang sama, dan perbezaan inilah yang menyebabkan konfigurasi gagal.

• Kebanyakan ejen memerlukan endpoint yang serasi dengan OpenAI. Berikan URL asas http://localhost:11434/v1 dan sebarang rentetan kunci API yang tidak kosong.
• Claude Code langsung tidak menerima URL asas OpenAI. Alat ini menggunakan Anthropic Messages API, jadi ANTHROPIC_BASE_URL perlu ditetapkan kepada http://localhost:11434, iaitu lokasi Ollama menyediakan /v1/messages.
• Codex menggunakan OpenAI Responses API. Ollama turut menyediakan /v1/responses, yang ditambahkan dalam versi 0.13.3.
• Ejen yang tidak menyediakan tetapan URL asas tidak boleh diarahkan semula kerana endpoint tersebut dibina terus dalam klien. Letakkan lapisan terjemahan di hadapannya, seperti gateway LiteLLM yang dihoskan sendiri, kemudian dedahkan semula model anda dalam format yang diperlukan oleh klien.

Ollama boleh menulis konfigurasi ini untuk anda. ollama launch opencode memulakan OpenCode dengan konfigurasi sebaris untuk model yang anda pilih, ollama launch claude melakukan perkara yang sama untuk Claude Code, manakala ollama launch droid --config menulis konfigurasi tanpa melancarkan alat tersebut.

Pasang Ollama dan tarik model yang boleh memanggil alat

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama ls

Pemasang menambah unit systemd dan memulakannya, jadi systemctl status ollama sepatutnya memaparkan active (running). Jika tidak, journalctl -e -u ollama akan memaparkan sebabnya.

Model itu mesti menyokong panggilan alat kerana panggilan alat ialah cara ejen berfungsi. Ejen membaca fail, menulis patch, menjalankan ujian, kemudian membaca kegagalan dan mencuba lagi. Model yang tidak boleh menghasilkan panggilan alat akan menerangkan perubahan dalam bentuk prosa dan bukannya melaksanakannya, lalu ejen akan mengulangi proses atau berhenti. Cari label tools pada halaman model di ollama.com sebelum anda menariknya. qwen3-coder:30b mempunyai label itu, dan setakat August 2026, tag tersebut ialah muat turun 19 GB dengan tetingkap konteks 256K. Jika mesin anda hanya menggunakan CPU atau mempunyai RAM yang terhad, aritmetik memori untuk tag Qwen 27B pada VPS menunjukkan perkara yang benar-benar muat dalam 8 hingga 64 GB sebelum anda memulakan muat turun. Selepas anda menariknya, gigabait tersebut akan disimpan pada cakera root pelayan, iaitu bahagian VPS yang paling terhad ruangnya. Oleh itu, lokasi Ollama menyimpan fail model dan cara memindahkannya ke tempat lain wajar dibaca sebelum cakera penuh.

Sekarang sahkan nama yang sebenarnya disediakan oleh pelayan:

curl http://localhost:11434/v1/models

Rentetan dalam respons itu ialah nilai yang mesti terkandung dalam konfigurasi ejen anda, aksara demi aksara. Semakan ini terlebih dahulu biasanya menyelesaikan kebanyakan ralat model tidak ditemui. Jika Ollama belum dipasang, panduan yang lebih panjang terdapat dalam cara mengehos sendiri LLM dengan Ollama pada VPS.

Halakan OpenCode kepada Ollama

Edit ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": {
          "name": "qwen3-coder 30b"
        }
      }
    }
  }
}

Kunci di bawah models ialah nama model yang dihantar kepada Ollama. Oleh itu, nilainya mesti sepadan tepat dengan ollama ls. Medan name hanya digunakan sebagai label dalam pemilih model. Mulakan opencode, tukar kepada penyedia Ollama dan pantau journalctl -e -u ollama untuk mengesahkan bahawa permintaan tiba di pelayan anda, bukan di tempat lain. Penyediaan ejen itu sendiri diterangkan dalam menjalankan OpenCode pada VPS.

Claude Code diarahkan ke Ollama

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30b

ANTHROPIC_API_KEY sengaja ditetapkan kepada rentetan kosong. Jika kunci sebenar dibiarkan dalam persekitaran, permintaan anda akan dihantar ke API yang dihoskan. Akibatnya, anda akan dikenakan bayaran dan tidak menggunakan inferens setempat. ollama launch claude menetapkan semua ini untuk anda.

Ketahui perkara yang tidak disediakan oleh lapisan keserasian ini. Lapisan ini tidak melaksanakan tool_choice atau caching prompt, dan tiada endpoint pengiraan token. Oleh itu, jumlah token yang anda lihat hanyalah anggaran berdasarkan tokenizer model itu sendiri. Claude Code turut disertakan dengan system prompt yang besar dan set alat yang besar, jadi ia memerlukan konteks yang lebih banyak berbanding klien sembang. Persoalan yang lebih luas tentang perkara yang boleh digunakan semula dan perkara yang tidak boleh digunakan semula diterangkan dalam sama ada anda boleh mengehos sendiri Claude.

Halakan Aider kepada Ollama

export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30b

Dokumentasi Aider mengesyorkan awalan ollama_chat/ berbanding ollama/. Anda juga boleh menetapkan tetingkap konteks bagi setiap model dalam .aider.model.settings.yml. Ini berguna apabila satu model memerlukan tetingkap yang berbeza daripada nilai lalai pelayan:

- name: ollama_chat/qwen3-coder:30b
  extra_params:
    num_ctx: 65536

Mengapa persediaan yang berfungsi masih menghasilkan output yang tidak masuk akal

Inilah bahagian yang penting. Ollama memilih panjang konteks lalai berdasarkan VRAM (memori video pada GPU) yang dapat dikesannya, dan nilai lalai itu diterbitkan:

[
  {
    "label": "Under 24 GiB VRAM",
    "default_context_tokens": "4,096"
  },
  {
    "label": "24 to 48 GiB VRAM",
    "default_context_tokens": "32,768"
  },
  {
    "label": "48 GiB VRAM or more",
    "default_context_tokens": "262,144"
  }
]

Kebanyakan pelan VPS, serta semua pelayan CPU sahaja, berada pada baris pertama: 4,096 token. Hanya GPU yang besar mendapat 262,144 token pada baris terakhir.

Ejen menggunakan 4096 token sebelum menjalankan sebarang kerja. Gesaan sistem, takrifan alat, senarai repositori dan fail pertama yang dibukanya sudah melebihi jumlah itu. Selepas itu, inilah masalah sebenarnya: tiada ralat berlaku. Dokumentasi Aider menyatakan bahawa Ollama membuang konteks yang melebihi tetingkap secara senyap. Token paling lama dikeluarkan, lalu model memberikan jawapan dengan yakin tentang fail yang tidak lagi dapat dilihatnya, atau melupakan arahan yang anda berikan dua langkah sebelumnya. Mekanisme ini menyebabkan kebanyakan laporan bahawa model tempatan terlalu lemah untuk menulis kod. Memilih jumlah itu sendiri ialah keputusan yang berasingan, dan kos num_ctx dalam memori cache KV bagi setiap saiz wajar dibaca sebelum anda menetapkan nilainya.

Dokumentasi Ollama menyatakan bahawa tugas seperti ejen dan alat pengekodan hendaklah ditetapkan kepada sekurang-kurangnya 64000 token. Tetapkannya pada pelayan:

sudo systemctl edit ollama.service

Tambahkan baris ini dalam fail override:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"

Kemudian muat semula dan mulakan semula:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ollama ps

ollama ps ialah pemeriksaan tersebut. Ia mencetak lajur CONTEXT, dan nombor itu ialah nilai yang sebenarnya diterima oleh model. Nilai ID dan SIZE anda akan berbeza:

NAME               ID              SIZE     PROCESSOR    CONTEXT    UNTIL
qwen3-coder:30b    a1b2c3d4e5f6    24 GB    100% GPU     64000      4 minutes from now

Tetapkannya pada pelayan, bukan dalam ejen, atas dua sebab. Skema OpenAI chat completions tidak mempunyai medan untuk panjang konteks, jadi klien yang serasi dengan OpenAI tidak dapat memintanya. Selain itu, tetapan ini adalah untuk setiap pelayan, jadi setiap ejen yang anda halakan ke pelayan itu akan mewarisinya. Bahagian output mempunyai hadnya sendiri, dan tidak seperti panjang konteks, nilai ini dihantar melalui endpoint keserasian. Oleh itu, num_predict dan medan max_tokens yang dipetakan kepadanya ialah tetapan yang perlu digunakan apabila balasan berhenti di tengah-tengah patch. Jika satu model memerlukan tetingkap yang berbeza, masukkannya ke dalam salinan menggunakan Modelfile:

FROM qwen3-coder:30b
PARAMETER num_ctx 65536

ollama create qwen3-coder-64k -f Modelfile

Konteks bukan percuma. Tetingkap yang lebih panjang menggunakan lebih banyak memori, jadi pantau lajur PROCESSOR. 100% GPU ialah nilai yang anda perlukan. Apabila sebahagian model beralih ke CPU, kadar token menurun sehingga gelung ejen tidak lagi boleh digunakan. Mengukur token sesaat pada LLM tempatan ialah cara untuk mencari had sebenar pelayan anda. Cara menentukan saiz mesin sebelum membelinya diterangkan dalam jumlah RAM dan CPU yang diperlukan oleh VPS ejen pengekodan.

Kekalkan model dimuatkan antara permintaan

Secara lalai, Ollama menyahmuat model 5 minit selepas permintaan terakhir. Tingkah laku ini sesuai untuk kotak sembang tetapi tidak sesuai untuk kerja ejen. Anda berhenti seketika untuk membaca diff, pemasa tamat, kemudian permintaan seterusnya memuatkan semula puluhan gigabait pemberat dari cakera sebelum token pertama dipaparkan. Keadaan ini kelihatan seperti proses tergantung.

OLLAMA_KEEP_ALIVE menerima rentetan tempoh seperti 10m atau 24h, nombor biasa dalam saat, -1 untuk mengekalkan model dimuatkan tanpa had, atau 0 untuk menyahmuatnya serta-merta. Tetapkannya bersebelahan dengan panjang konteks:

[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"

Medan permintaan keep_alive hanya tersedia pada endpoint asli Ollama, iaitu /api/generate dan /api/chat, bukan pada endpoint keserasian. Oleh itu, ejen tidak boleh menetapkannya bagi setiap permintaan. Pemboleh ubah persekitaran ialah satu-satunya kawalan yang tersedia. Apabila anda memerlukan semula memori tersebut, ollama stop qwen3-coder:30b menyahmuat model tanpa menghentikan pelayan. Jika anda mahu tetapan ini kekal selepas reboot, atau mahu menilai sama ada pemberat perlu dikekalkan dalam memori sepanjang hari berbanding mendapatkan semula memori itu, mengekalkan model Ollama dimuatkan dalam memori menyokong kedua-dua keperluan tersebut.

Menjalankan Ollama pada pelayan berasingan

Ollama terikat pada localhost. Untuk mengaksesnya dari mesin lain, tetapkan OLLAMA_HOST=0.0.0.0:11434 dalam override systemd yang sama dan mulakan semula servis.

Lakukan ini hanya pada rangkaian peribadi. Dokumentasi Ollama menyatakan bahawa API tempatan tidak memerlukan pengesahan. Oleh itu, port 11434 yang dibuka kepada Internet membolehkan sesiapa sahaja menggunakan perkakasan anda dan membaca apa-apa yang dihantar oleh ejen anda. Terdapat dua pilihan yang selamat. Kekalkan ikatan pada localhost dan majukan port melalui SSH dari komputer riba anda:

ssh -N -L 11434:localhost:11434 you@your-vps

Ejen anda terus menggunakan http://localhost:11434/v1 dan tidak menyedari perbezaannya. Pilihan lain ialah VPN, dengan Ollama terikat pada alamat VPN dan bukannya 0.0.0.0. Jika beberapa orang atau beberapa ejen akan berkongsi satu mesin, penjadual Ollama tidak direka untuk beban tersebut, dan perbandingan antara Ollama dan vLLM menunjukkan apabila perbezaan daya pemprosesan mula menjejaskan prestasi.

Bila model pengekodan tempatan lebih baik, dan bila tidak

Ejen yang dipacu oleh model yang anda hoskan sendiri tidak menggantikan API frontier untuk setiap tugasan. Model ini jelas lebih baik untuk empat jenis kerja.

• Pengeditan mekanikal secara pukal, apabila setiap perubahan kecil dan boleh disemak. Menamakan semula merentas repositori, menambah petunjuk jenis, menulis docstring dan menterjemah komen. Model boleh berjalan selama berjam-jam tanpa menambah kos.
• Kerja yang tidak boleh meninggalkan perkakasan anda. Contohnya, kod klien di bawah perjanjian kerahsiaan atau repositori dalaman yang tidak dibenarkan dihantar kepada pihak ketiga.
• Mesin luar talian dan air-gapped, yang langsung tidak mempunyai API terhos untuk dipanggil.
• Kos yang boleh dijangka. Selepas kos pelayan dibayar, ejen yang menggunakan token dalam gelung tidak menambah kos, berbeza dengan API bermeter. Bila GPU VPS mencapai titik pulang modal berbanding token API mengandungi pengiraan tersebut.

Model ini kurang sesuai untuk tugasan berbilang langkah yang panjang. “Cari sebab ujian ini gagal, baiki puncanya dan kemas kini pemanggil” memerlukan banyak panggilan alat yang betul secara berturut-turut, dengan keseluruhan sejarah masih berada dalam konteks. Model dalam julat 8B hingga 14B pada pelayan sederhana mungkin menghasilkan panggilan alat yang tidak sah atau melupakan pelan selepas beberapa giliran. Akibatnya, anda menghabiskan lebih banyak masa untuk membimbingnya berbanding masa yang diperlukan untuk menyiapkan tugasan. Ini bukan masalah prompt yang boleh diselesaikan hanya dengan menulis prompt yang lebih baik. Ini ialah masalah kapasiti.

Model ini juga kurang sesuai apabila kesilapan membawa kos tinggi dan anda tidak akan membaca setiap baris. Berikan model tempatan tugasan yang khusus dan semak hasilnya. Gunakan model terhos untuk kerja yang tidak dapat anda semak langkah demi langkah.

Mod kegagalan dan rentetan yang akan anda lihat

curl: (7) Failed to connect to localhost port 11434 after 0 ms: Connection refused. Pelayan tidak berjalan, atau ejen diarahkan ke hos yang berbeza. Jalankan systemctl status ollama, kemudian journalctl -e -u ollama.

Ejen melaporkan bahawa model tidak wujud. Nama dalam konfigurasi anda tidak sepadan dengan nama yang disediakan oleh pelayan. Bandingkan nama itu dengan curl http://localhost:11434/v1/models dan salin rentetan tersebut dari situ. Teg itu ialah sebahagian daripada nama, jadi konfigurasi yang menamakan teg yang tidak pernah anda tarik akan gagal walaupun model yang serupa telah dipasang.

Ejen menjawab dalam bentuk prosa dan tidak pernah mengedit fail. Model itu mungkin tidak menyokong alat, atau permintaan bersama takrif alatnya sudah memenuhi keseluruhan tetingkap konteks. Semak label tools pada halaman model, kemudian semak lajur CONTEXT dalam ollama ps.

Senyap lama sebelum token pertama, kemudian kelajuan normal. Keep-alive telah tamat tempoh dan pemberat model sedang dibaca semula dari cakera. Tetapkan OLLAMA_KEEP_ALIVE.

Model bercanggah dengan fail yang baru dibacanya. Ini ialah pemotongan konteks. ollama ps biasanya menunjukkan nilai CONTEXT yang lebih kecil daripada nilai yang anda fikir telah ditetapkan, kerana pemboleh ubah persekitaran itu ditetapkan pada shell anda dan bukannya pada unit systemd.

Semuanya berfungsi, tetapi perlahan, dan PROCESSOR bukan 100% GPU. Model bersama konteksnya tidak muat dalam VRAM. Kurangkan panjang konteks, atau gunakan model yang lebih kecil atau quantisation yang lebih kecil. Sebelum anda menarik semula model, kos memori q4_K_M, q8_0 dan fp16 serta tempat kualiti sebenar mula merosot menerangkan jumlah ruang yang diperoleh dengan menurunkan satu tahap dan perkara yang perlu dikorbankan.

FAQ

Bolehkah saya mengarahkan Claude Code kepada Ollama?

Ya, tetapi bukan dengan URL yang serasi dengan OpenAI. Claude Code menggunakan Anthropic Messages API, manakala Ollama menyediakan format tersebut pada /v1/messages menggunakan port yang sama, iaitu 11434. Eksport ANTHROPIC_BASE_URL=http://localhost:11434 dan ANTHROPIC_AUTH_TOKEN=ollama, kemudian tetapkan ANTHROPIC_API_KEY sebagai nilai kosong sebelum memulakannya dengan claude --model qwen3-coder:30b. ollama launch claude menulis tetapan yang sama untuk anda. Lapisan keserasian ini tidak melaksanakan tool_choice atau caching prompt, dan tidak mempunyai endpoint pengiraan token. Oleh itu, jumlah token yang dilaporkan hanyalah anggaran.

Mengapakah model setempat saya menjawab tentang kod yang tidak dapat dilihatnya?

Kerana permintaan itu tidak lagi muat dalam tetingkap konteks, lalu bahagian paling awal digugurkan tanpa ralat. Ollama menetapkan konteks lalai berdasarkan VRAM yang dikesannya. Jika VRAM kurang daripada 24 GiB, nilai lalainya ialah 4,096 token, sedangkan prompt sistem dan takrif alat untuk ejen sahaja sudah melebihi jumlah tersebut. Tetapkan OLLAMA_CONTEXT_LENGTH=64000 dalam unit systemd, mulakan semula Ollama dan pastikan lajur CONTEXT dalam ollama ps memaparkan nilai baharu.

Model manakah yang patut saya jalankan untuk ejen pengekodan pada VPS?

Pilih model terbesar yang mempunyai label tools dan masih muat dalam memori dengan tetingkap konteks 64k. Utamakan model yang dioptimumkan untuk kod. qwen3-coder:30b ialah pilihan lazim pada pelayan GPU dengan VRAM yang mencukupi. Jika tag itu terlalu besar untuk pelayan anda, angka RAM dan kelajuan mod CPU sahaja untuk Nemotron 3.5 Lightning boleh dijadikan perbandingan sebelum anda memulakan muat turun. Di bawah kira-kira 14B parameter, model masih boleh menjawab soalan tentang kod dengan baik tetapi gagal melakukan pengeditan berbilang langkah. Ini kerana tugas ejen sangat terjejas oleh kesilapan pemformatan kecil dalam panggilan alat. Uji model dengan satu tugas sebenar daripada repositori anda sendiri, bukan prompt contoh.

Adakah saya memerlukan GPU untuk menjalankan ejen pengekodan pada model sendiri?

Dalam amalan, ya. Inferens CPU sahaja boleh berfungsi dan memadai untuk soalan tunggal, tetapi ejen menghantar banyak permintaan bagi setiap tugas dan membaca semula sejarah yang panjang untuk setiap permintaan. Oleh itu, kadar token yang rendah boleh mengubah tugas selama dua minit menjadi satu jam. Semak lajur PROCESSOR dalam ollama ps. Sebarang nilai selain 100% GPU bermakna sebahagian model dijalankan pada CPU, lalu kadar token menurun dengan ketara.