Jupyter调用Qwen3-0.6B全步骤，含base

Jupyter调用Qwen3-0.6B全步骤，含base_url设置细节

1. 为什么在Jupyter里调用Qwen3-0.6B值得你花5分钟读完

你刚启动了Qwen3-0.6B镜像，Jupyter Lab界面已经打开，但卡在“怎么连上模型”这一步？复制文档里的代码却报错ConnectionRefusedError或Invalid URL？别急——这不是你环境的问题，而是base_url配置有隐藏细节。

Qwen3-0.6B镜像默认以API服务形式运行在容器内部，而Jupyter运行在同一容器内，这意味着：你不需要填公网地址，也不该填localhost:8000。很多开发者踩坑就在这里——把文档里示例的https://gpu-pod.../v1直接复制粘贴，结果发现根本连不通。

本文将带你从零开始，不跳过任何一个关键细节：
启动后如何确认服务已就绪
base_url到底该填什么（附3种常见场景判断法）
LangChain调用时extra_body参数的真实作用
如何验证调用成功并避免“静默失败”
一个能直接运行、带错误排查提示的完整示例

全程基于真实镜像环境操作，所有命令和代码均可一键复现。

2. 启动镜像与服务状态确认

2.1 镜像启动后的第一件事：检查API服务是否就绪

镜像启动后，Jupyter Lab会自动打开。但此时Qwen3-0.6B的推理API服务可能还在加载中（尤其首次启动需加载模型权重）。不要急于写代码，先确认服务状态：

在Jupyter中新建一个Terminal（顶部菜单 → File → New → Terminal），执行：

# 检查API服务进程是否运行 ps aux | grep "uvicorn" | grep -v grep # 查看服务监听端口（默认8000） netstat -tuln | grep :8000 # 直接测试本地HTTP接口（关键！） curl -s http://127.0.0.1:8000/health | jq .

预期输出应为：

{"status":"healthy","model":"Qwen3-0.6B"}

如果返回curl: (7) Failed to connect或超时，请等待30-60秒后重试。模型加载完成前，服务不可用。

2.2 理解base_url的本质：不是域名，而是容器内通信地址

文档中给出的base_url="https://gpu-pod694e6fd3bffbd265df09695a-8000.web.gpu.csdn.net/v1"是部署平台生成的公网访问地址，仅用于外部系统（如你的本地电脑）调用。但在Jupyter环境中，你和模型服务同处一个容器，应使用容器内网地址：

调用场景	正确base_url格式	说明
Jupyter内调用（本文场景）	`http://127.0.0.1:8000/v1`	最简高效，无DNS开销，推荐首选
同一宿主机其他程序调用	`http://host.docker.internal:8000/v1`	Docker Desktop兼容，Linux需额外配置
外部网络调用	`https://xxx.web.gpu.csdn.net/v1`	文档示例地址，需确保平台已开放外网访问

关键结论：在Jupyter中，永远用http://127.0.0.1:8000/v1，而非文档中的HTTPS地址。这是90%连接失败的根源。

3. LangChain调用Qwen3-0.6B完整实践

3.1 安装必要依赖（仅首次需要）

在Jupyter中新建一个Python Notebook，运行以下单元格：

# 安装LangChain核心包（镜像已预装transformers、torch等） !pip install langchain-openai==0.1.42 --quiet # 验证安装 import pkg_resources print("langchain-openai版本:", pkg_resources.get_distribution("langchain-openai").version)

3.2 构建ChatOpenAI实例：base_url与参数详解

from langchain_openai import ChatOpenAI import os # 关键：使用容器内网地址，协议为http（非https） chat_model = ChatOpenAI( model="Qwen3-0.6B", # 模型标识名，必须与镜像一致 temperature=0.5, # 创意性控制：0=确定性，1=高随机性 base_url="http://127.0.0.1:8000/v1", # 核心修正点！ api_key="EMPTY", # Qwen3 API要求固定值，非密钥 extra_body={ # 传递Qwen3特有参数 "enable_thinking": True, # 启用思维链推理（适合复杂问题） "return_reasoning": True, # 返回推理过程（非仅最终答案） }, streaming=True, # 启用流式响应，适合长输出 ) # 测试调用（带错误捕获） try: response = chat_model.invoke("你是谁？请用中文回答，不超过30字。") print(" 调用成功！模型回复：", response.content.strip()) except Exception as e: print("❌ 调用失败：", str(e)) print(" 常见原因：1. 服务未就绪 2. base_url协议错误（用了https） 3. 端口非8000")

3.3`extra_body`参数深度解析：不只是开关

extra_body字典向Qwen3 API透传原生参数。对Qwen3-0.6B而言，这两个键值至关重要：

参数	类型	作用	推荐场景
`enable_thinking`	bool	控制是否启用思维链（Chain-of-Thought）模式	数学题、逻辑推理、多步任务
`return_reasoning`	bool	是否在响应中包含完整推理过程（含`<think>`标签）	需要可解释性的调试、教学场景

实际效果对比：
enable_thinking=False：直接输出答案，速度快，适合简单问答
enable_thinking=True+return_reasoning=True：返回类似<think>第一步...第二步...</think><output>最终答案</output>的结构化响应，便于解析推理步骤

3.4 流式响应处理：避免卡顿的实用技巧

streaming=True时，invoke()返回AIMessageChunk对象。若直接打印可能显示乱码。正确处理方式：

from langchain_core.messages import AIMessageChunk def stream_response(query: str): """安全的流式响应处理函数""" try: stream = chat_model.stream(query) full_content = "" print(" 模型正在思考并生成...") for chunk in stream: if isinstance(chunk, AIMessageChunk): content = chunk.content or "" full_content += content # 实时打印（避免换行干扰） print(content, end="", flush=True) print("\n\n 完整响应：", full_content.strip()) return full_content except Exception as e: print(f"\n❌ 流式调用异常：{e}") return None # 示例调用 stream_response("用Python写一个计算斐波那契数列前10项的函数")

4. 常见问题排查与解决方案

4.1 连接被拒绝（ConnectionRefusedError）

现象：requests.exceptions.ConnectionError: HTTPConnectionPool(host='127.0.0.1', port=8000): Max retries exceeded...

根因与解决：

❌ 错误：base_url写成https://127.0.0.1:8000/v1（HTTP服务不支持HTTPS）
正确：base_url="http://127.0.0.1:8000/v1"（协议必须为http）
❌ 错误：服务未启动完成，curl http://127.0.0.1:8000/health返回空
解决：在Terminal中执行curl -s http://127.0.0.1:8000/health，等待返回{"status":"healthy"}后再运行代码

4.2 API密钥错误（Authentication Error）

现象：openai.AuthenticationError: No API key provided

根因与解决：
Qwen3 API要求api_key字段存在，但值必须为字符串"EMPTY"（区分大小写）。

❌ 错误：api_key=""、api_key=None、api_key="empty"
正确：api_key="EMPTY"（全大写）

4.3 模型名称不匹配（NotFoundError）

现象：openai.NotFoundError: The model 'Qwen-0.6B' does not exist

根因与解决：
镜像中注册的模型名是Qwen3-0.6B，非Qwen-0.6B。

❌ 错误：model="Qwen-0.6B"（文档旧版命名）
正确：model="Qwen3-0.6B"（查看镜像启动日志确认）

快速确认模型名：在Terminal中执行
curl -s http://127.0.0.1:8000/v1/models | jq '.data[0].id'
输出应为"Qwen3-0.6B"

4.4 响应为空或超时

现象：response.content为空字符串，或等待超过30秒无响应

优化方案：

# 在ChatOpenAI初始化中增加超时与重试 chat_model = ChatOpenAI( model="Qwen3-0.6B", temperature=0.5, base_url="http://127.0.0.1:8000/v1", api_key="EMPTY", extra_body={"enable_thinking": False}, # 简单问题禁用思考模式提速 timeout=30.0, # 单次请求超时30秒 max_retries=1, # 减少重试避免卡顿 )

5. 进阶技巧：绕过LangChain直接调用API

当LangChain封装无法满足需求时（如需精确控制headers、处理二进制响应），可直接使用requests：

import requests import json def direct_qwen3_api(prompt: str, enable_thinking: bool = True): """绕过LangChain，直连Qwen3 API""" url = "http://127.0.0.1:8000/v1/chat/completions" headers = { "Content-Type": "application/json", "Authorization": "Bearer EMPTY" # 注意：Bearer后跟EMPTY } data = { "model": "Qwen3-0.6B", "messages": [{"role": "user", "content": prompt}], "temperature": 0.5, "extra_body": { "enable_thinking": enable_thinking, "return_reasoning": enable_thinking } } try: response = requests.post(url, headers=headers, json=data, timeout=60) response.raise_for_status() result = response.json() return result["choices"][0]["message"]["content"] except requests.exceptions.RequestException as e: print(f"API请求失败：{e}") return None # 示例 print("直接调用结果：", direct_qwen3_api("1+1等于几？"))

6. 总结：Jupyter调用Qwen3-0.6B的黄金法则

6.1 三步快速上手清单

启动后必做：在Terminal执行curl http://127.0.0.1:8000/health，确认返回healthy
base_url铁律：Jupyter内调用 →http://127.0.0.1:8000/v1（http协议，非https）
参数三要素：model="Qwen3-0.6B"+api_key="EMPTY"+extra_body按需设置

6.2 避坑指南：高频错误对照表

错误现象	根本原因	修复动作
ConnectionRefused	base_url协议错误或服务未就绪	改`https`→`http`，检查`/health`接口
AuthenticationError	api_key值不为`"EMPTY"`	确保`api_key="EMPTY"`（全大写）
ModelNotFoundError	模型名拼写错误	执行`curl .../v1/models`确认ID
响应缓慢/超时	启用了思考模式处理简单问题	`extra_body={"enable_thinking": False}`