企业官网建设流程全解析

如何用 Ollama 本地模型驱动 Parlant：环境变量与模型拉取配置

【免费下载链接】parlantBuild reliable customer-facing AI agents with Parlant: an interaction control harness optimized for controlled, consistent, and predictable LLM interactions.项目地址: https://gitcode.com/GitHub_Trending/pa/parlant

当你不想把对话数据发给云端 LLM 提供商，或者需要一台离线可用的对话 Agent 时，可以让 Parlant 使用本机 Ollama 提供文本生成和向量化（embedding）能力。Parlant 内置了 Ollama NLP Service，接入方式只有两步：设置四个OLLAMA_*环境变量，再用ollama pull预拉取生成模型和嵌入模型。本文覆盖从安装 Parlant、配置环境变量、拉取模型，到启动服务和排查典型错误的完整路径。

准备条件

以下前置要求来自 安装文档 与 Ollama 服务文档：

• Python 3.10 及以上；
• Parlant 本体：pip install parlant。部分 NLP 提供商需要额外安装 extra 依赖，Ollama 对应的 extra 会引入 Python 客户端库（版本要求见 pyproject.toml 中的ollama = ["ollama>=0.5.0"]），可以安装parlant[ollama]；
• Ollama 本体已安装并运行。Ollama 服务文档列出三项前置：安装 Ollama（从 ollama.ai 官网下载）、启动 Ollama 服务器（ollama serve，通常会自动启动）、预拉取所需模型。

ollama serve

Ollama 本地运行，不需要 API key；如果要把 Ollama 服务器暴露到外部网络，文档提醒需要考虑防火墙规则。

配置 Ollama 环境变量

Ollama 服务通过以下四个环境变量配置：

# Ollama server URL (default: http://localhost:11434) export OLLAMA_BASE_URL="http://localhost:11434" # Model size to use (default: 4b) # Options: gemma3:1b, gemma3:4b, llama3.1:8b, gemma3:12b, gemma3:27b, llama3.1:70b, llama3.1:405b export OLLAMA_MODEL="gemma3:4b" # Embedding model (default: nomic-embed-text) # Options: nomic-embed-text, mxbai-embed-large export OLLAMA_EMBEDDING_MODEL="nomic-embed-text" # API timeout in seconds (default: 300) export OLLAMA_API_TIMEOUT="300"

各变量的默认值与可选值以文档注释为准：OLLAMA_BASE_URL默认http://localhost:11434；OLLAMA_MODEL默认 4b 档，可选项如上注释所列；OLLAMA_EMBEDDING_MODEL默认nomic-embed-text；OLLAMA_API_TIMEOUT默认 300 秒。

文档给出的两套示例配置（文档示例，可按硬件情况二选一）：

# For development (fast, good balance) export OLLAMA_MODEL="gemma3:4b" export OLLAMA_EMBEDDING_MODEL="nomic-embed-text" export OLLAMA_API_TIMEOUT="180" # higher accuracy cloud export OLLAMA_MODEL="gemma3:4b" export OLLAMA_EMBEDDING_MODEL="nomic-embed-text" export OLLAMA_API_TIMEOUT="600"

文档在“Custom / Other models”小节还展示了换用非默认型号的方式（文档示例）：

export OLLAMA_MODEL=llama3.2:3b export OLLAMA_API_TIMEOUT=300

拉取所需模型

文档特别强调：在运行 Parlant 之前先拉取模型，否则首次使用时可能因下载模型触发 API 超时。

最常用的组合（文本生成 + 嵌入）：

# Recommended for most use cases (good balance of speed/accuracy) ollama pull gemma3:4b-it-qat # Fast but may struggle with complex schemas ollama pull gemma3:1b # embedding model required for creating embeddings ollama pull nomic-embed-text

文档的选型建议表（内存需求与定位均来自文档）：

大模型档位仅限云端或高端硬件，例如llama3.1:70b需要 40GB+ GPU 显存，llama3.1:405b需要 200GB+（cloud-only）：

# Better reasoning capabilities ollama pull llama3.1:8b # High accuracy for complex tasks ollama pull gemma3:12b # Very high accuracy (requires more resources) ollama pull gemma3:27b-it-qat # ⚠️ WARNING: Requires 40GB+ GPU memory ollama pull llama3.1:70b # ⚠️ WARNING: Requires 200GB+ GPU memory (cloud-only) ollama pull llama3.1:405b

注意一个细节：OLLAMA_MODEL的默认值写的是gemma3:4b，而文档推荐拉取的标签是gemma3:4b-it-qat。文档在故障排查一节对Model gemma3:4b not found错误给出的解决方案正是ollama pull gemma3:4b-it-qat，两者按文档说明配套使用即可，不需要额外改动环境变量。

可选分支：自定义嵌入模型

默认嵌入模型nomic-embed-text无需额外配置。如需换用其他嵌入模型，文档说明：把OLLAMA_EMBEDDING_MODEL设为目标模型名，并在启动服务前设置与你的嵌入模型兼容的OLLAMA_EMBEDDING_VECTOR_SIZE；文档用snowflake-arctic-embed（向量维度 1024）测试过。使用nomic-embed-text、mxbai-embed-large或bge-m3时无需设置OLLAMA_EMBEDDING_VECTOR_SIZE，维度分别默认为 768、1024、1024。文档还给出的替代嵌入模型（512 维）：

ollama pull mxbai-embed-large:latest

用 Ollama 服务启动 Parlant

环境变量和模型就绪后，创建Server时指定nlp_service=NLPServices.ollama（Ollama 文档中的 Usage Example，文档示例）：

import parlant.sdk as p from parlant.sdk import NLPServices async with p.Server(nlp_service=NLPServices.ollama) as server: agent = await server.create_agent( name="Healthcare Agent", description="Is empathetic and calming to the patient.", )

Ollama 服务不支持流式输出，只承担文本生成与向量化；文档开头明确了该服务的定位是 "local LLM capabilities ... supports both text generation and embeddings"。

验证结果

Parlant 在创建 Ollama 服务时会先做校验（见 ollama_service.py）：

1. 环境变量校验：OLLAMA_BASE_URL、OLLAMA_MODEL、OLLAMA_EMBEDDING_MODEL、OLLAMA_API_TIMEOUT任一缺失时，报错信息会直接列出缺了哪个变量以及对应的export语句，例如export OLLAMA_MODEL="gemma3"。看到这类提示时按输出补齐环境变量即可。
2. 模型校验：服务会向OLLAMA_BASE_URL发起请求并列出本地模型。缺少模型时，报错会逐条给出需要执行的ollama pull命令并附上当前可用模型列表；无法连接时（状态码 502/503/504）会提示确认ollama serve是否在运行、OLLAMA_BASE_URL是否正确。

功能层面的验证沿用安装文档的做法：启动程序后打开http://localhost:8800，新建一个会话并与 Agent 对话，能收到符合 Agent 描述的回复即说明 Ollama 驱动的生成链路可用。

常见问题排查

Ollama 文档的 Troubleshooting 一节列出的错误现象与对应处理：

1. Model Not Found：Model gemma3:4b not found. Please pull it first with: ollama pull gemma3:4b—— 解决方案：启动 Parlant 前先执行ollama pull gemma3:4b-it-qat。
2. Connection Error：Cannot connect to Ollama server at http://localhost:11434—— 确认 Ollama 正在运行（ollama serve）。
3. Timeout Error：Request timed out after 300s—— 调大OLLAMA_API_TIMEOUT，或换更小的模型。
4. Out of Memory：CUDA out of memory—— 换更小的模型档位，或增加 GPU 显存。

文档给出的性能优化建议：首次使用前预拉取模型；大模型调大超时；选能满足精度要求的最小模型；监控 GPU 占用并据此调整模型尺寸。

限制说明

• 70b / 405b 档位分别要求 40GB+ 与 200GB+ GPU 显存，文档标注仅适合云端或高端硬件；本地开发文档建议用gemma3:4b或更小。
• Ollama 不支持流式文本生成，这是该服务的固有边界，不是配置问题。
• 数据不出本机、无需 API key 是文档 Security Notes 一节给出的安全特性；若把 Ollama 服务器暴露到外部网络，需要自行考虑防火墙规则。

【免费下载链接】parlantBuild reliable customer-facing AI agents with Parlant: an interaction control harness optimized for controlled, consistent, and predictable LLM interactions.项目地址: https://gitcode.com/GitHub_Trending/pa/parlant