Learning objectives
By the end of this module, you should be able to:
- Distinguish the Ollama CLI from the Ollama service and model runtime.
- Call a local model through HTTP instead of treating the CLI as magic.
- Explain localhost, port 11434 and the /api boundary in simple networking terms.
- Diagnose common local failures such as service unavailable, wrong model name and remote-host binding issues.
🎓 Learning Coach follows this block when it is centered in your browser
The command, the service and the model are different things
A CLI command is a client interface. The Ollama service is the long-running process that accepts API requests. The model is the set of weights and runtime behavior used to generate output. CPU or GPU hardware performs the computation.
Keeping these pieces separate makes errors easier to interpret. A missing model is different from a stopped service, and both are different from insufficient memory.
- CLI/client: asks for work.
- Service: listens for requests and manages model execution.
- Model: weights/configuration used for generation.
- Hardware: CPU/GPU and memory resources used by the runtime.
Common beginner misconceptionClosing a terminal client does not necessarily mean the model service stopped. Client lifecycle and server lifecycle are separate.
🎓 Learning Coach follows this block when it is centered in your browser
localhost:11434 is a network address, even on one machine
Ollama's local API is served by default at http://localhost:11434/api. `localhost` means the same machine as the client process. `11434` is the TCP port where the service listens, and `/api` is the API path prefix.
This becomes important when the client runs inside a container or on another machine: its `localhost` is no longer your Ollama host.
- localhost / 127.0.0.1: local loopback interface.
- 11434: default Ollama service port.
- /api/generate and /api/chat: generation interfaces.
- Remote clients need a reachable bind address, routing/firewall rules and appropriate access controls.
Common beginner misconceptionA connection-refused error is not an LLM reasoning failure. It is a service/network failure.
🎓 Learning Coach follows this block when it is centered in your browser
Calling the API removes the magic
Once Ollama is running, a client can send JSON to its HTTP API. The request names a model and supplies input. The service returns generated data, often as a stream of JSON objects unless streaming is disabled for that endpoint.
Seeing the raw request is valuable because later gateways and applications are simply creating, forwarding and governing similar requests.
- HTTP method and path select the operation.
- JSON carries model and input parameters.
- The response may stream incrementally.
- HTTP/network errors and model-generation errors should be diagnosed separately.
Common beginner misconceptionThe important thing is to understand the boundary and evidence before memorizing implementation details.
🎓 Learning Coach follows this block when it is centered in your browser
Troubleshoot from the outside inward
When local inference fails, begin with the cheapest evidence: is the service process running, is the port reachable, does the API respond, is the requested model available, and only then inspect model/resource behavior.
Changing several things at once destroys evidence. Test one boundary at a time.
- Process: is Ollama running?
- Socket: is something listening on the expected address/port?
- API: does a simple endpoint respond?
- Model: is the requested model present/valid?
- Resources: is memory/accelerator capacity sufficient?
Common beginner misconceptionThe important thing is to understand the boundary and evidence before memorizing implementation details.
Worked examples
Call Ollama directly
curl http://localhost:11434/api/generate \
-d '{"model":"<your-model>","prompt":"Explain latency simply.","stream":false}'
- Use a model name that actually exists on your system.
- The default local API base is http://localhost:11434/api.
- Setting stream:false makes this first inspection easier; streaming comes next.
Layered diagnosis
1. process → is the service running?
2. socket → is port 11434 reachable?
3. API → does HTTP respond?
4. model → is the requested model available?
5. resource → can it fit/run?
- Move inward one boundary at a time.
- Do not treat every local-model failure as a GPU problem.
Try it · core lab · account-free
Operate a tiny model-service simulator, then optionally compare Ollama
Goal: Understand client/server/API boundaries with no dependencies, then map the same ideas onto a real local Ollama installation if available.
Before you start
- Core lab: Python 3 only.
- Optional extension: a local Ollama installation and any model you already have. The core lab does not download a model.
STEP 1Run the built-in self-test
python3 public/labs/llmops/03_model_service_basics.py --self-test
STEP 2Start the tiny HTTP service
python3 public/labs/llmops/03_model_service_basics.py --serve
STEP 3From another terminal, call it
curl -s http://127.0.0.1:18080/api/generate -H 'Content-Type: application/json' -d '{"model":"learning-model","prompt":"hello"}'
STEP 4Optional: repeat against Ollama
If Ollama is installed, inspect its local API with a model already present on your system. Compare the same client → service → model mental model.
Verify
- The self-test proves the client can reach the service and receive structured JSON.
- Stopping the service causes a connection failure before any 'model' logic runs.
- You can explain why 127.0.0.1:18080 in this lab is analogous to Ollama's local service address.
Expected outcome
- You see HTTP as the boundary between a client and a model-serving process.
- You can classify connection, API and model errors separately.
Break / fix · diagnose
- If port 18080 is already in use, stop the conflicting process or run the self-test only; do not blindly kill unrelated services.
- If a real Ollama request fails, verify service reachability before changing model parameters.
- If Ollama runs remotely, remember that your client's localhost is not the remote server.
Production viewThe same client/server reasoning applies whether the backend is Ollama, vLLM, a managed provider or an internal inference service.
Avoid these traps
Common mistakes
- Treating the Ollama CLI, server process and model as one indistinguishable thing.
- Assuming localhost always refers to the physical host where Ollama is installed.
- Exposing a model service to the network without thinking about access control.
- Debugging prompts when the actual error is connection refused.
Knowledge check
Reason about the system, not just the vocabulary.
Answer before opening each explanation. Opening all four answers records knowledge-check activity in My Learning.
1What listens on port 11434 in a normal local Ollama setup?
The Ollama API service. Clients such as curl or the CLI communicate with that service.
2Why can `localhost` be confusing with containers?
Each container has its own network namespace; localhost refers to the container itself, not automatically to the host.
3What should you verify before investigating model quality when curl says connection refused?
Verify the service process, bind address, port and network path first.
4Why call the local HTTP API during training instead of using only `ollama run`?
The HTTP call exposes the actual client/server contract that applications, gateways and platform services will use later.