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

如何用 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 [ollama0.5.0]可以安装parlant[ollama]Ollama 本体已安装并运行。Ollama 服务文档列出三项前置安装 Ollama从 ollama.ai 官网下载、启动 Ollama 服务器ollama serve通常会自动启动、预拉取所需模型。ollama serveOllama 本地运行不需要 API key如果要把 Ollama 服务器暴露到外部网络文档提醒需要考虑防火墙规则。配置 Ollama 环境变量Ollama 服务通过以下四个环境变量配置# Ollama server URL (default: http://localhost:11434) export OLLAMA_BASE_URLhttp://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_MODELgemma3:4b # Embedding model (default: nomic-embed-text) # Options: nomic-embed-text, mxbai-embed-large export OLLAMA_EMBEDDING_MODELnomic-embed-text # API timeout in seconds (default: 300) export OLLAMA_API_TIMEOUT300各变量的默认值与可选值以文档注释为准OLLAMA_BASE_URL默认http://localhost:11434OLLAMA_MODEL默认 4b 档可选项如上注释所列OLLAMA_EMBEDDING_MODEL默认nomic-embed-textOLLAMA_API_TIMEOUT默认 300 秒。文档给出的两套示例配置文档示例可按硬件情况二选一# For development (fast, good balance) export OLLAMA_MODELgemma3:4b export OLLAMA_EMBEDDING_MODELnomic-embed-text export OLLAMA_API_TIMEOUT180 # higher accuracy cloud export OLLAMA_MODELgemma3:4b export OLLAMA_EMBEDDING_MODELnomic-embed-text export OLLAMA_API_TIMEOUT600文档在“Custom / Other models”小节还展示了换用非默认型号的方式文档示例export OLLAMA_MODELllama3.2:3b export OLLAMA_API_TIMEOUT300拉取所需模型文档特别强调在运行 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文档的选型建议表内存需求与定位均来自文档Model SizeUse CaseMemory RequirementsPerformance1bQuick testing, simple tasks~2GBFast but limited accuracy4bRecommended for development~4GBGood balance of speed/accuracy8bcomplex reasoning~8GBBetter reasoning than Gemma12bHigh-accuracy tasks~12GBHigh accuracy, slower27bComplex workloads~27GBVery high accuracy70bEnterprise/cloud only~40GBExcellent accuracy405bResearch/cloud only~200GBState-of-the-art大模型档位仅限云端或高端硬件例如llama3.1:70b需要 40GB GPU 显存llama3.1:405b需要 200GBcloud-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_serviceNLPServices.ollamaOllama 文档中的 Usage Example文档示例import parlant.sdk as p from parlant.sdk import NLPServices async with p.Server(nlp_serviceNLPServices.ollama) as server: agent await server.create_agent( nameHealthcare Agent, descriptionIs empathetic and calming to the patient., )Ollama 服务不支持流式输出只承担文本生成与向量化文档开头明确了该服务的定位是 local LLM capabilities ... supports both text generation and embeddings。验证结果Parlant 在创建 Ollama 服务时会先做校验见 ollama_service.py环境变量校验OLLAMA_BASE_URL、OLLAMA_MODEL、OLLAMA_EMBEDDING_MODEL、OLLAMA_API_TIMEOUT任一缺失时报错信息会直接列出缺了哪个变量以及对应的export语句例如export OLLAMA_MODELgemma3。看到这类提示时按输出补齐环境变量即可。模型校验服务会向OLLAMA_BASE_URL发起请求并列出本地模型。缺少模型时报错会逐条给出需要执行的ollama pull命令并附上当前可用模型列表无法连接时状态码 502/503/504会提示确认ollama serve是否在运行、OLLAMA_BASE_URL是否正确。功能层面的验证沿用安装文档的做法启动程序后打开http://localhost:8800新建一个会话并与 Agent 对话能收到符合 Agent 描述的回复即说明 Ollama 驱动的生成链路可用。常见问题排查Ollama 文档的 Troubleshooting 一节列出的错误现象与对应处理Model Not FoundModel gemma3:4b not found. Please pull it first with: ollama pull gemma3:4b—— 解决方案启动 Parlant 前先执行ollama pull gemma3:4b-it-qat。Connection ErrorCannot connect to Ollama server at http://localhost:11434—— 确认 Ollama 正在运行ollama serve。Timeout ErrorRequest timed out after 300s—— 调大OLLAMA_API_TIMEOUT或换更小的模型。Out of MemoryCUDA 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考