企业官网建设流程全解析

LangChain 基础介绍 #Term

LangChain：连接 Python 与各大大模型厂商的胶水框架，统一封装模型调用、智能体、RAG 等能力，兼容阿里云百炼、DeepSeek、OpenAI 等所有兼容 OpenAI 接口的模型。

官网地址：https://docs.langchain.com/ 中文文档：docs.langchain.org.cn/oss/

一、环境安装配置

1. 配置国内清华 pip 源（加速下载）

shell

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

2. 必备依赖包

shell

pip install langchain langchain-openai openai python-dotenv langchain-core

二、大模型调用三件套

1. 阿里云百炼平台接入

平台地址：https://bailian.console.aliyun.com/cn-beijing#/home

前置准备

1. 获取 API Key（平台密钥管理页面生成）
2. 获取业务空间 WorkspaceId（控制台业务空间域名内标识）
3. 选择平台内置模型：qwen-plus、qwen3.7-max 等（不支持 DeepSeek 系列）

写法 1：LangChain 0.3 旧版 ChatOpenAI

python

运行

#1.导入依赖 from langchain_openai import ChatOpenAI from openai import OpenAI import os from dotenv import load_dotenv # 加载.env环境变量，解决中文乱码 load_dotenv(encoding='utf-8') # 读取配置 workspace_id = os.getenv("ALI_WORKSPACE_ID") llm = ChatOpenAI( model='qwen-plus', api_key=os.getenv('QWEN_API_KEY'), # 拼接完整合法接口地址 base_url=f'https://{workspace_id}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1' ) # 调用模型 response = llm.invoke("你是谁") print(response) # 完整元数据对象 print(response.content) # 仅打印模型回答文本

写法 2：LangChain 1.0 新版 init_chat_model（推荐）

python

运行

#1导入依赖 import os from dotenv import load_dotenv from langchain.chat_models import init_chat_model # 加载环境变量 load_dotenv(encoding="utf-8") #2.实例化模型 model = init_chat_model( model='qwen-plus', model_provider='openai', api_key=os.getenv('aliQwen-api'), base_url='https://{你的WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1' ) #3.调用模型 print(model.invoke('你是谁').content) print("*" * 50)

[!tip] 多模型共存思路：同一项目可同时初始化多个厂商模型，业务层统一封装调度，按需切换调用。

2. DeepSeek 模型接入

官方平台：https://platform.deepseek.com/usage 核心要点：独立接口地址，密钥与阿里云不通用，阿里云百炼无法调用 DeepSeek 模型。

python

运行

#1导入依赖 import os from dotenv import load_dotenv from langchain.chat_models import init_chat_model load_dotenv(encoding="utf-8") #2.实例化模型 model = init_chat_model( model='deepseek-v4-flash', model_provider='openai', api_key=os.getenv('DEEPSEEK_API_KEY'), base_url='https://api.deepseek.com/v1' ) #3.调用模型 print(model.invoke('你是谁').content) print("*" * 50)

三、通用 .env 配置文件（统一管理密钥，禁止硬编码）

env

# 阿里云百炼配置 QWEN_API_KEY=sk-xxx ALI_WORKSPACE_ID=ws-xxx aliQwen-api=sk-xxx # DeepSeek配置 DEEPSEEK_API_KEY=sk-xxx DEEPSEEK_BASE_URL=https://api.deepseek.com/v1 DEEPSEEK_MODEL=deepseek-v4-flash # LLM全局推理参数 LLM_TIMEOUT=60 LLM_TEMPERATURE=0.7

四、两种模型调用方式 #Term

1. 同步调用 invoke ()一次性请求，等待模型生成完整文本后统一返回；适合短问答，长文本会阻塞等待，无实时打字效果。
2. 流式调用 stream ()【重点】模型分段输出文本分片 chunk，循环实时读取；前端交互体验更好，避免长时间空白卡顿。 使用模板：

python

运行

for chunk in model.stream("提问内容"): print(chunk.content, end="")

五、企业级强制编码规范 #Rule

1. 日志规范禁止使用 print 输出业务日志，统一使用logging模块；分级打印 INFO/DEBUG/ERROR，携带时间戳方便线上排错。
2. 环境变量管理密钥、接口地址全部存入.env，禁止硬编码；代码启动时必须做非空校验，密钥缺失直接抛出清晰异常；.env 加入.gitignore 不提交代码仓库。
3. 模型初始化封装统一封装init_llm_client()函数，集中管理模型名称、超时、温度等参数，全局复用。
4. 分层精细化异常捕获区分配置异常、网络异常、接口业务错误；识别常见错误码：401 密钥失效、402 账户余额不足、404 模型不存在。
5. 程序入口保护使用if __name__ == "__main__":包裹主逻辑，避免文件被导入时自动执行；顶层全局 try-except 兜底，防止程序崩溃。

六、LangChain 架构版本对比 #Compare

表格

七、企业级标准完整代码 #Code

python

运行

import os import logging from dotenv import load_dotenv from langchain.chat_models import init_chat_model from langchain_core.language_models import BaseChatModel from openai import APIStatusError, APIConnectionError # 1. 全局日志标准化配置 logging.basicConfig( level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S" ) logger = logging.getLogger("LLM-Service") # 2. 加载并校验环境变量 def load_env_config() -> dict: load_dotenv(encoding="utf-8") config = { "api_key": os.getenv("DEEPSEEK_API_KEY"), "base_url": os.getenv("DEEPSEEK_BASE_URL", "https://api.deepseek.com/v1"), "model_name": os.getenv("DEEPSEEK_MODEL", "deepseek-v4-flash"), "timeout": int(os.getenv("LLM_TIMEOUT", 60)), "temperature": float(os.getenv("LLM_TEMPERATURE", 0.7)) } if not config["api_key"]: raise ValueError("DEEPSEEK_API_KEY 未配置，请检查项目.env文件") logger.info("环境变量加载校验完成") return config # 3. 统一封装模型初始化函数 def init_llm_client(config: dict) -> BaseChatModel: logger.info(f"初始化模型：{config['model_name']}") llm = init_chat_model( model=config["model_name"], model_provider="openai", api_key=config["api_key"], base_url=config["base_url"], timeout=config["timeout"], temperature=config["temperature"] ) logger.info("模型客户端初始化成功") return llm # 4. 同步调用业务方法 def sync_chat(llm: BaseChatModel, query: str) -> str: logger.info(f"同步调用，提问：{query}") resp = llm.invoke(query) logger.info("同步调用完成") return resp.content # 5. 流式输出业务方法 def stream_chat(llm: BaseChatModel, query: str): logger.info(f"流式调用，提问：{query}") full_text = "" for chunk in llm.stream(query): chunk_txt = chunk.content full_text += chunk_txt logger.debug(f"流式分片：{chunk_txt}") yield chunk_txt logger.info(f"流式输出结束，总文本长度：{len(full_text)}") # 6. 程序入口 + 全局异常捕获 if __name__ == "__main__": user_question = "请介绍一下LangGraph" try: env_cfg = load_env_config() llm_client = init_llm_client(env_cfg) # 同步调用演示 logger.info("========== 同步 invoke 调用 ==========") sync_result = sync_chat(llm_client, user_question) logger.info(f"同步返回结果：\n{sync_result}") # 流式调用演示 logger.info("========== 流式 stream 调用 ==========") stream_total = "" for piece in stream_chat(llm_client, user_question): stream_total += piece logger.info(f"流式完整内容：\n{stream_total}") except ValueError as ve: logger.error(f"配置参数异常：{str(ve)}") except APIStatusError as se: if se.status_code == 402: logger.error("调用失败：账户余额不足，请充值后重试") elif se.status_code == 401: logger.error("调用失败：API密钥无效或已过期") elif se.status_code == 404: logger.error("调用失败：模型名称不存在，请核对参数") else: logger.error(f"接口异常，状态码：{se.status_code}") except APIConnectionError: logger.error("网络异常，无法连接模型服务商接口") except Exception as e: logger.error(f"程序未知异常：{str(e)}", exc_info=True)

八、高频报错汇总 #Error

1. ValueError: DEEPSEEK_API_KEY 未配置原因：.env 文件缺失、变量名写错、未执行load_dotenv()加载配置
2. 402 Insufficient BalanceDeepSeek 账户余额不足；可切换阿里云百炼使用免费额度测试
3. 401 鉴权失败API 密钥复制错误、密钥过期、密钥权限不足
4. 404 模型不存在模型名称拼写错误；阿里云接口地址不可调用 DeepSeek 模型

九、配套 .gitignore 企业规范

plaintext

# 敏感环境配置 .env .env.* # 虚拟环境目录 .venv/ venv/ # Python缓存文件 __pycache__/ *.pyc # 日志文件 *.log logs/