Guna Ollama dengan Ejen Pengekodan Anda
Tetapkan URL asas Ollama pada port 11434, gunakan kunci API palsu, dan elakkan masalah context length sambil mengenal pasti tugasan yang sesuai untuk model setempat.
Perkara yang anda sambungkan
Anda boleh menggunakan Ollama dengan ejen pengekodan anda, dan sambungannya lebih ringkas daripada jangkaan ramai. Anda hanya perlu menukar satu URL asas dan memilih satu nama model. Medan kunci API masih memerlukan nilai, tetapi pelayan tempatan akan mengabaikannya, jadi sebarang rentetan aksara boleh digunakan.
Ollama mendengar pada port 11434 dan menyediakan tiga permukaan API pada masa yang sama. /api ialah API asli Ollama. /v1 ialah lapisan yang serasi dengan OpenAI, yang merangkumi beberapa bentuk: /v1/chat/completions, /v1/responses, /v1/completions, /v1/models dan /v1/embeddings. Dokumentasi Ollama menyatakan bahawa kunci di situ diperlukan tetapi diabaikan. Permukaan ketiga adalah serasi dengan Anthropic: klien mengambil http://localhost:11434 sebagai URL asasnya dan menambah /v1/messages, iaitu protokol yang digunakan oleh Claude Code. Kebanyakan ejen menggunakan /v1/chat/completions, Codex menggunakan /v1/responses, dan Claude Code menggunakan /v1/messages. Ejen anda sudah menyokong salah satu daripada ini, jadi tiada perkara lain yang perlu diubah.
Bahagian itu mengambil masa lima minit. Sama ada hasilnya boleh digunakan atau tidak bergantung pada dua tetapan yang jarang diubah oleh sesiapa, iaitu panjang konteks (context length) dan keep-alive, serta memberikan model jenis tugasan yang sesuai dengan keupayaannya. Kedua-duanya mempunyai bahagian tersendiri, dan had sebenar dinyatakan di bahagian akhir.
Ejen pengekodan yang menerima base URL tempatan
Ujiannya hanya satu soalan: adakah alat tersebut mendedahkan tetapan base URL? Jika ya, ia boleh berhubung dengan pelayan anda.
Ollama menerbitkan halaman integrasi untuk Claude Code, OpenCode, Codex, Cline, Roo Code, Zed, IDE JetBrains dan VS Code. Aider mendokumentasikan sokongan Ollama miliknya secara berasingan. Ini merangkumi kebanyakan perkara yang dimaksudkan oleh orang ramai sebagai ejen pengekodan pada Oktober 2026. Tidak semua ejen menggunakan format yang sama, dan perbezaan itulah punca kegagalan persediaan.
- Kebanyakan ejen mahukan endpoint yang serasi dengan OpenAI. Berikan mereka base URL
http://localhost:11434/v1dan sebarang rentetan API key yang tidak kosong. - Claude Code tidak menerima base URL OpenAI sama sekali. Ia menggunakan Anthropic Messages API, jadi ia memerlukan
ANTHROPIC_BASE_URLditetapkan kepadahttp://localhost:11434, di mana Ollama menyediakan/v1/messages. - Codex menggunakan OpenAI Responses API. Ollama juga menyediakan
/v1/responses, yang ditambah dalam versi 0.13.3. - Ejen tanpa tetapan base URL tidak boleh diubah hala, kerana endpoint tersebut terbina dalam klien. Jika ejen menerima URL tersuai tetapi memerlukan format API yang berbeza, letakkan lapisan terjemahan di hadapan, seperti gateway LiteLLM yang dihoskan sendiri, dan dedahkan semula model anda dalam format yang diminta 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, dan ollama launch droid --config menulis konfigurasi tersebut tanpa melancarkan alat berkenaan.
Pasang Ollama dan tarik model yang boleh memanggil alatan
curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama --no-pager
ollama pull qwen3-coder:30b
ollama lsPemasang menambah unit systemd dan memulakannya, jadi systemctl status ollama sepatutnya memaparkan active (running). Jika tidak, journalctl -e -u ollama akan memaparkan puncanya.
Model tersebut mesti menyokong pemanggilan alatan, kerana pemanggilan alatan adalah cara ejen berfungsi. Ia membaca fail, menulis patch, menjalankan ujian, kemudian membaca kegagalan dan mencuba semula. Model yang tidak boleh mengeluarkan panggilan alatan akan menerangkan suntingan dalam bentuk prosa dan bukannya melaksanakannya, lalu ejen akan berulang atau berhenti. Cari label tools pada halaman model di ollama.com sebelum anda menariknya. qwen3-coder:30b menyokongnya, dan setakat Oktober 2026 tag tersebut merupakan muat turun bersaiz 19 GB dengan tetingkap konteks 256K. Jika pelayan anda hanya menggunakan CPU atau kekurangan RAM, pengiraan memori untuk tag Qwen 27B pada VPS menunjukkan apa yang sebenarnya muat dalam 8 hingga 64 GB sebelum anda memulakan muat turun. Sebaik sahaja anda menariknya, gigabait tersebut akan disimpan pada cakera root pelayan, iaitu bahagian VPS yang paling terhad ruangnya, jadi tempat Ollama menyimpan fail modelnya dan cara memindahkannya ke tempat lain perlu dibaca sebelum cakera penuh.
Sekarang, sahkan nama yang sebenarnya disediakan oleh pelayan:
curl http://localhost:11434/v1/modelsRentetan dalam respons tersebut adalah apa yang mesti terkandung dalam konfigurasi ejen anda, aksara demi aksara. Memeriksanya terlebih dahulu akan menyelesaikan kebanyakan ralat model-not-found. Jika Ollama belum dipasang, panduan yang lebih panjang terdapat dalam pengehosan kendiri 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.
Halakan Claude Code ke Ollama
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model qwen3-coder:30bANTHROPIC_API_KEY sengaja dibiarkan sebagai rentetan kosong. Base URL mengawal ke mana permintaan dihantar; mengosongkan kunci ini memastikan kelayakan (credentials) yang dihoskan tidak termasuk dalam persediaan tempatan ini. ollama launch claude menetapkan semua ini untuk anda.
Fahami perkara yang tidak disertakan oleh lapisan keserasian (compatibility layer). Ia tidak melaksanakan tool_choice atau caching prompt, dan ia tidak mempunyai endpoint pengiraan token, jadi nombor token yang anda lihat adalah anggaran daripada tokenizer model itu sendiri. Claude Code juga menghantar system prompt yang besar dan set alat yang luas, jadi ia memerlukan konteks yang lebih banyak berbanding klien sembang. Soalan yang lebih luas tentang perkara yang dibawa bersama dan perkara yang tidak disertakan diliputi dalam sama ada anda boleh mengehos sendiri Claude.
Menghalakan Aider ke Ollama
export OLLAMA_API_BASE=http://127.0.0.1:11434
aider --model ollama_chat/qwen3-coder:30bDokumentasi Aider mengesyorkan awalan ollama_chat/ berbanding ollama/. Secara lalai, Aider meminta konteks yang mencukupi bagi setiap permintaan ditambah 8k token untuk balasan. Ia juga membolehkan anda menetapkan tetingkap konteks bagi setiap model dalam .aider.model.settings.yml, yang berguna apabila satu model memerlukan tetingkap yang berbeza daripada lalai pelayan:
- name: ollama_chat/qwen3-coder:30b
extra_params:
num_ctx: 65536Mengapa persediaan yang berfungsi masih menghasilkan output yang tidak masuk akal
Ini adalah bahagian yang penting. Ollama memilih panjang konteks lalai berdasarkan jumlah VRAM (memori video pada GPU) yang dapat dikesan, dengan menolak OLLAMA_GPU_OVERHEAD bagi setiap GPU yang dikesan. Pelaksanaannya menggunakan ambang berikut:
Data di sebalik carta ini
[
{
"label": "Under 23 GiB aggregate VRAM",
"default_context_tokens": "4,096"
},
{
"label": "23 to under 47 GiB aggregate VRAM",
"default_context_tokens": "32,768"
},
{
"label": "47 GiB aggregate VRAM or more",
"default_context_tokens": "262,144"
}
]Kebanyakan pelan VPS, dan setiap pelayan yang hanya menggunakan CPU, berada dalam baris pertama: 4,096 token. Berbilang GPU yang lebih kecil boleh mencapai ambang 47 GiB secara bersama untuk 262,144 token dalam baris terakhir.
Sesuatu ejen akan menggunakan 4096 token sebelum ia memulakan sebarang kerja. Prompt sistem, definisi alat, senarai repositori, dan fail pertama yang dibuka sudah pun melebihi saiz tersebut. Masalah sebenar berlaku selepas itu: tiada ralat yang dipaparkan. Dokumentasi Aider menyatakan bahawa Ollama membuang konteks yang melebihi tetingkap secara senyap. Token yang paling lama akan dibuang, menyebabkan model menjawab dengan yakin tentang fail yang tidak lagi dapat dilihatnya, atau melupakan arahan yang anda berikan dua langkah sebelumnya. Mekanisme inilah punca utama laporan yang menyatakan model tempatan terlalu lemah untuk menulis kod. Memilih nombor tersebut adalah keputusan anda sendiri, dan kos num_ctx dalam memori cache KV pada setiap saiz wajar dibaca sebelum anda menetapkan satu nilai.
Dokumentasi Ollama menyatakan bahawa tugas seperti ejen dan alat pengekodan harus ditetapkan kepada sekurang-kurangnya 64000 token. Tetapkan nilai ini pada pelayan:
sudo systemctl edit ollama.serviceTambahkan 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 psHantar permintaan daripada ejen anda selepas memulakan semula, kemudian jalankan ollama ps sekali lagi supaya terdapat model yang dimuatkan untuk diperiksa. ollama ps ialah semakannya. Ia mencetak lajur CONTEXT, dan nombor tersebut adalah apa yang sebenarnya diterima oleh model. ID dan SIZE anda akan berbeza:
NAME ID SIZE PROCESSOR CONTEXT RUNNER UNTIL
qwen3-coder:30b a1b2c3d4e5f6 24 GB 100% GPU 64000 ggml 4 minutes from nowTetapkan nilai pada pelayan dan bukannya pada ejen, atas dua sebab. Skema OpenAI chat completions tidak mempunyai medan untuk panjang konteks, jadi klien yang serasi dengan OpenAI tidak boleh memintanya. Selain itu, tetapan lalai pelayan terpakai kepada setiap ejen kecuali jika model atau permintaan mengatasi tetapan tersebut. Bahagian output mempunyai hadnya sendiri, dan tidak seperti panjang konteks, ia dihantar melalui endpoint keserasian, jadi num_predict dan medan max_tokens yang memetakannya adalah perkara yang perlu dirujuk apabila balasan terhenti di tengah-tengah patch. Jika satu model memerlukan tetingkap yang berbeza, masukkan tetapan tersebut ke dalam salinan dengan Modelfile:
FROM qwen3-coder:30b
PARAMETER num_ctx 65536ollama create qwen3-coder-64k -f ModelfileKonteks tidak percuma. Tetingkap yang lebih panjang memerlukan lebih banyak memori, jadi perhatikan lajur PROCESSOR. 100% GPU adalah apa yang anda mahukan. Apabila sebahagian daripada model beralih ke CPU, kadar token akan jatuh sehingga gelung ejen menjadi tidak boleh digunakan, dan mengukur token sesaat pada LLM tempatan adalah cara anda mencari had sebenar untuk mesin anda. Saiz mesin sebelum anda membelinya dibincangkan dalam berapa banyak RAM dan CPU yang diperlukan oleh VPS ejen pengekodan.
Pastikan model kekal dimuatkan antara permintaan
Secara lalai, Ollama akan memunggah (unload) model 5 minit selepas permintaan terakhir. Tetapan ini sesuai untuk kotak sembang tetapi tidak sesuai untuk kerja ejen. Anda berhenti seketika untuk membaca diff, pemasa tamat, dan permintaan seterusnya akan memuatkan semula puluhan gigabait pemberat (weights) daripada cakera sebelum token pertama muncul. Ini kelihatan seperti sistem tergantung (hang).
OLLAMA_KEEP_ALIVE menerima rentetan tempoh seperti 10m atau 24h, nombor saat yang biasa, -1 untuk memastikan model kekal dimuatkan selama-lamanya, atau 0 untuk memunggah serta-merta. Tetapkan nilai ini di samping panjang konteks:
[Service]
Environment="OLLAMA_CONTEXT_LENGTH=64000"
Environment="OLLAMA_KEEP_ALIVE=-1"Medan permintaan keep_alive wujud pada endpoint asli /api/generate dan /api/chat Ollama serta sebagai sambungan Ollama pada /v1/chat/completions. Ejen yang mendedahkan medan permintaan tambahan boleh menghantarnya ke sana; jika tidak, gunakan pemboleh ubah persekitaran (environment variable). Apabila anda memerlukan memori tersebut kembali, ollama stop qwen3-coder:30b akan memunggah model tanpa menghentikan pelayan. Jika anda mahu tetapan ini kekal selepas but semula, atau ingin menimbang antara mengekalkan pemberat dalam memori sepanjang hari dengan mendapatkan semula memori tersebut, mengekalkan model Ollama dimuatkan dalam memori berfungsi untuk kedua-duanya.
Menjalankan Ollama pada pelayan berasingan
Ollama terikat pada localhost. Untuk mencapainya dari mesin lain, tetapkan OLLAMA_HOST=0.0.0.0:11434 dalam override systemd yang sama dan mulakan semula servis tersebut.
Lakukan perkara ini hanya pada rangkaian peribadi. Dokumentasi Ollama menyatakan bahawa tiada pengesahan diperlukan untuk API tempatan, jadi port 11434 yang terbuka kepada internet bermakna sesiapa sahaja boleh menggunakan perkakasan 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-vpsEjen anda terus menghala ke http://localhost:11434/v1 dan tidak akan menyedari sebarang perbezaan. 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 kotak, Ollama menyokong permintaan selari apabila memori mencukupi, dan perbandingan antara Ollama dan vLLM menunjukkan di mana perbezaan throughput 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 dihalakan 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 ia dengan curl http://localhost:11434/v1/models dan salin rentetan dari situ. Tag adalah sebahagian daripada nama, jadi konfigurasi yang menamakan tag yang tidak pernah anda tarik akan gagal walaupun model yang serupa telah dipasang.
Ejen menjawab dalam bentuk prosa dan tidak pernah menyunting fail. Sama ada model tidak mempunyai sokongan alat, atau permintaan berserta definisi alatnya telah memenuhi tetingkap konteks. Semak label tools pada halaman model, kemudian semak lajur CONTEXT dalam ollama ps.
Keheningan yang lama sebelum token pertama, kemudian kelajuan kembali normal. Keep-alive telah tamat tempoh dan pemberat sedang dibaca semula daripada cakera. Tetapkan OLLAMA_KEEP_ALIVE.
Model bercanggah dengan fail yang baru dibacanya. Pemotongan konteks (context truncation). ollama ps biasanya menunjukkan nilai CONTEXT yang lebih kecil daripada yang anda sangka telah ditetapkan, kerana pemboleh ubah persekitaran pergi ke shell anda dan bukannya ke unit systemd.
Semuanya berfungsi, tetapi perlahan, dan PROCESSOR menunjukkan 100% CPU atau pembahagian CPU/GPU. Biasanya model berserta konteksnya tidak muat dalam VRAM. Jika PROCESSOR membaca 100% CPU pada mesin yang mempunyai GPU, singkirkan punca lain terlebih dahulu: Ollama mungkin tidak menemui GPU tersebut langsung. Dokumentasi Ollama menyatakan bahawa pada Linux, selepas kitaran suspend/resume, ia kadangkala gagal mengesan GPU NVIDIA dan kembali menggunakan CPU, dan memuatkan semula pemacu dengan sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm dapat mengatasi masalah ini. Jika GPU ditemui dan pembahagian masih berlaku, rendahkan panjang konteks, atau beralih kepada model yang lebih kecil atau kuantisasi yang lebih kecil. Sebelum anda menarik semula, kos memori bagi q4_K_M, q8_0 dan fp16, serta tahap penurunan kualiti memberitahu anda berapa banyak ruang yang diperoleh dengan satu langkah penurunan dan apa yang anda korbankan untuknya. Unknown juga merupakan nilai PROCESSOR yang mungkin; ia tidak menetapkan offloading CPU.
FAQ
Bolehkah saya menghalakan Claude Code kepada Ollama?
Boleh, tetapi bukan menggunakan URL yang serasi dengan OpenAI. Claude Code menggunakan Anthropic Messages API, dan Ollama menyediakan bentuk tersebut pada /v1/messages pada port 11434 yang sama. Eksport ANTHROPIC_BASE_URL=http://localhost:11434, ANTHROPIC_AUTH_TOKEN=ollama dan ANTHROPIC_API_KEY yang kosong, kemudian mulakannya dengan claude --model qwen3-coder:30b. ollama launch claude akan menulis tetapan yang sama untuk anda. Lapisan keserasian ini tidak melaksanakan tool_choice atau caching prompt, dan ia tidak mempunyai endpoint pengiraan token, jadi jumlah token yang dilaporkan adalah anggaran sahaja.
Mengapakah model tempatan saya menjawab tentang kod yang tidak dapat dilihatnya?
Ini kerana permintaan tersebut tidak lagi muat dalam tetingkap konteks, dan bahagian paling lama telah digugurkan tanpa sebarang ralat. Ollama menetapkan konteks lalai berdasarkan jumlah VRAM yang dikesan selepas menolak overhead yang dikonfigurasikan bagi setiap GPU: di bawah 23 GiB, nilai lalainya ialah 4,096 token, dari 23 hingga bawah 47 GiB ialah 32,768 token, dan pada 47 GiB atau lebih ialah 262,144 token. Tetapkan OLLAMA_CONTEXT_LENGTH=64000 dalam unit systemd, mulakan semula Ollama, dan sahkan bahawa lajur CONTEXT dalam ollama ps menunjukkan nilai baharu tersebut.
Model manakah yang patut saya jalankan untuk ejen pengekodan pada VPS?
Pilih model terbesar yang membawa label tools yang masih muat dalam memori dengan tetingkap konteks 64k, dan utamakan model yang ditala untuk kod. qwen3-coder:30b ialah jawapan biasa pada pelayan GPU yang mempunyai VRAM mencukupi. Jika tag tersebut terlalu besar untuk pelayan anda, angka RAM dan kelajuan CPU-sahaja untuk Nemotron 3.5 Lightning adalah perbandingan yang berguna sebelum anda memulakan muat turun. Di bawah kira-kira 14B parameter, model masih boleh menjawab soalan tentang kod dengan baik tetapi akan gagal dalam suntingan berbilang langkah, kerana kerja ejen akan menghukum kesilapan pemformatan kecil dalam panggilan alat. Uji dengan satu tugasan sebenar daripada repositori anda sendiri dan bukannya menggunakan prompt contoh.
Adakah saya memerlukan GPU untuk menjalankan ejen pengekodan pada model saya sendiri?
Secara praktikalnya, ya. Inferens CPU-sahaja boleh berfungsi dan memadai untuk soalan tunggal, tetapi ejen menghantar banyak permintaan bagi setiap tugasan dan setiap satunya membaca semula sejarah yang panjang, jadi kadar token yang perlahan akan menjadikan tugasan dua minit kepada satu jam. Semak lajur PROCESSOR dalam ollama ps: 100% CPU atau pembahagian CPU/GPU menunjukkan penggunaan CPU, yang melambatkan inferens. Unknown tidak menetapkan offloading CPU.