Ollama Structured Fields in Python: A Practical Guide

Ollama can return model responses in a predictable JSON shape, making it easier to read named fields in a Python program instead of parsing free-form text. You’ll need Ollama running locally or on a reachable host, a model that supports structured output, and Python with the Ollama client installed.

What You’ll Need

Ollama installed and running. Start it with ollama serve if your installation does not already run the service.
A downloaded model. For example, download one with ollama pull llama3.1; choose a model available in your Ollama installation.
Python 3 and the Ollama Python package: python -m pip install ollama.
A Python script or interactive environment, and a clear definition of the fields and their types.

Step-by-Step

Check that Ollama is reachable. In a terminal, run ollama list and confirm your chosen model appears. If it does not, pull it first. The Python client normally connects to the local Ollama service at its default address; for a remote service, configure the client for that host and ensure it is reachable.
Define a schema for the response. A schema tells the model what fields to return and what type each field should have. Pydantic is a convenient way to define and validate that shape. Install it with python -m pip install pydantic, then create a model like this:
```
from pydantic import BaseModel

class Contact(BaseModel):
    name: str
    email: str
    age: int | None = None
```
In this example, name and email are required strings; age may be an integer or null. Use types that reflect the data you actually need. For older Python versions, use Optional[int] from typing instead of int | None.

Ask Ollama for a structured response. Save this as a Python file and adjust the prompt to suit your task:

from ollama import chat

response = chat(
    model='llama3.1',
    messages=[
        {
            'role': 'user',
            'content': 'Extract the contact details: Maya Chen, maya@example.com, age 29.'
        }
    ],
    format=Contact.model_json_schema(),
    options={'temperature': 0},
)

print(response.message.content)

The format argument accepts a JSON schema, such as the one Pydantic generates. A low temperature can make output more consistent, but it does not guarantee correctness. Replace the model name with one you have pulled.

Parse the returned JSON into fields. The response content is JSON text. Validate and convert it into a Pydantic object with model_validate_json:
```
contact = Contact.model_validate_json(response.message.content)

print(contact.name)
print(contact.email)
print(contact.age)
```
Now your program can access typed fields directly. Validation raises an error if the content is malformed or does not match the schema, rather than quietly treating an unexpected value as valid.

Handle missing or invalid data. Wrap the call and parsing in error handling for the application you are building. A simple pattern is:

from pydantic import ValidationError

try:
    response = chat(
        model='llama3.1',
        messages=[{'role': 'user', 'content': 'Extract: Maya Chen, maya@example.com, age 29.'}],
        format=Contact.model_json_schema(),
        options={'temperature': 0},
    )
    contact = Contact.model_validate_json(response.message.content)
except ValidationError as exc:
    print('The response did not match the schema:', exc)
except Exception as exc:
    print('Could not complete the Ollama request:', exc)

In a real application, log enough detail to diagnose failures while avoiding unnecessary storage of private input. Decide whether to retry, ask for a corrected response, or report that extraction failed.

Test edge cases before relying on the fields. Try incomplete records, ambiguous values, extra details, and text that contains no contact information. Confirm how optional fields should be represented and that required fields are not invented. Add constraints or application-level checks when a field must meet rules beyond its basic type.

Common Mistakes

Using a schema the model does not support well. Structured-output support and quality vary by model and Ollama version. If output repeatedly fails to follow the schema, update Ollama and try a compatible model.
Expecting the schema to prove facts are true. Schema validation checks shape and types, not whether an extracted email or age is accurate. Validate important values against your own trusted source or rules.
Parsing the wrong property. With the Python client, the generated content is at response.message.content. It is a string containing JSON, not already a Python dictionary.
Making every field required. If source text may omit a value, represent that possibility explicitly, such as with an optional field, and handle None downstream.
Assuming temperature zero makes results deterministic. It can reduce variation but cannot guarantee identical output or eliminate errors.

Tips

Keep the schema small and specific. Use descriptive field names and clear types, and add optional fields only when your application can handle them.
For repeated tasks, put extraction instructions in the prompt and explicitly say to use null or an empty list where appropriate. Make sure that convention agrees with the schema.
For lists or nested records, define nested Pydantic models and use types such as list[str]. Validate the complete response before using any of its fields.
Pin and test your Python dependencies in the project environment. Keep Ollama and the selected model consistent across development and deployment where possible.
Treat model-produced values as untrusted input. Escape or validate them before placing them in HTML, SQL, shell commands, or other sensitive contexts.

Troubleshooting

Connection refused or request times out: Confirm the Ollama service is running, the model is available, and the host and port are reachable. If you use a remote host, check the client configuration and network access rather than assuming the local default applies.

Model not found: Run ollama list, then pull the exact model name you use in chat(). Check spelling and any tag included in the name.

JSON or Pydantic validation errors: Print the response content during development, then compare it with the schema. Check whether a value is missing, has a different type, or uses a format your model does not handle consistently. Simplify the schema or prompt, and test another compatible model if needed.

Unexpected nulls or invented values: Make the prompt explicit about what to do when information is absent, and ensure optional fields allow that result. For consequential uses, require confirmation or a trusted verification step; structured output is not a guarantee of factual accuracy.

Import or method errors: Verify that the package is installed in the same Python environment running your script. Check the installed Ollama and Pydantic versions and consult their current documentation if an API differs.

Frequently Asked Questions

Does Ollama return a Python dictionary?
No. The chat response contains JSON text in response.message.content. Parse it with Pydantic or Python’s json module to access fields.

Do I have to use Pydantic?
No. You can pass a JSON schema directly and parse the response with json.loads(). Pydantic adds convenient type validation and clear model definitions.

Can I request nested fields or arrays?
Yes. Define nested schema objects and array types, then pass the resulting JSON schema through format. Test the model’s output against representative inputs.

What if a field is missing from the source text?
Make it optional or nullable in your schema and tell the model how to represent missing information. Check that your application handles the missing value safely.

Will structured output prevent hallucinations?
No. It constrains the response’s format, not the truth of its contents. Validate values and use a trusted source or human review when accuracy matters.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →