1. 项目概述从想法到产品的“最后一公里”最近和不少做AI应用的朋友聊天发现一个挺普遍的现象大家对于大语言模型LLM的能力都挺兴奋脑子里也攒了不少好点子比如做个智能客服、搞个文档分析助手或者搭个个性化的聊天机器人。但真到动手把想法变成代码、再把代码部署上线让用户能用的时候就卡住了。这个从“我有一个很棒的想法”到“用户真的能用上”的过程我们常戏称为“最后一公里”。这公里路往往比想象中要崎岖。问题出在哪呢直接调用大模型的原始API就像给你一堆钢筋水泥让你从零开始盖房子。你得自己处理对话历史管理、思考如何把用户问题和大模型能力对齐这就是提示工程、还得考虑如果一次回答不完怎么办处理长文本和复杂逻辑。更头疼的是当你的应用需要结合搜索、查数据库、调其他工具时代码会迅速变得复杂且难以维护。这就是为什么我们需要一个“框架”来帮忙。LangChain就是这个领域里目前最受瞩目的“脚手架”和“工具箱”它把LLM应用开发中那些重复、繁琐的环节抽象成模块让你能像搭积木一样快速构建应用。而百度智能云千帆则提供了一个稳定、可靠且功能丰富的“大模型供应基地”。它不止接入了文心一言还集成了国内外众多主流模型给你一个统一的平台进行管理、调用和对比。更重要的是千帆提供了配套的SDK软件开发工具包让你能方便地用代码和这些模型对话。所以这个项目的核心目标就非常明确了如何将LangChain这个强大的应用构建框架与百度千帆这个稳定的大模型服务平台通过其Python SDK无缝对接起来。这不是简单的API调用教学而是一套让开发者能快速、规范、可扩展地落地LLM应用的工程化方案。无论你是想快速验证一个AI点子还是为现有产品增加智能特性亦或是构建一个全新的AI原生应用这套组合都能帮你省下大量从零造轮子的时间把精力集中在业务逻辑和创新本身。2. 环境准备与核心工具选型解析工欲善其事必先利其器。在开始编码之前我们需要把“工作台”搭建好。这里的选择直接关系到后续开发的效率和应用的稳定性。2.1 Python环境与包管理构建稳固的基石首先Python是这一切的基础。我强烈建议使用Python 3.8 到 3.11之间的版本。这是目前绝大多数AI库兼容性最好的范围。避免使用最新的3.12或更老的3.7可能会遇到一些依赖库尚未适配或已停止支持的问题。安装Python后第一件事就是建立虚拟环境。这是一个好习惯能为每个项目创建独立的依赖库空间防止不同项目间的包版本冲突。# 使用 venv 创建虚拟环境推荐 python -m venv venv_llm_app # 激活虚拟环境 # 在 Windows 上 venv_llm_app\Scripts\activate # 在 macOS/Linux 上 source venv_llm_app/bin/activate激活后你的命令行提示符前会出现(venv_llm_app)字样表示你已经在这个独立环境中了。接下来是安装核心依赖。我们将使用pip进行安装。这里的关键是版本匹配尤其是LangChain其版本迭代较快API变动也可能发生。# 安装 LangChain 核心库。指定一个相对较新且稳定的版本。 pip install langchain0.1.0 # 安装 LangChain 社区库其中包含大量第三方集成包括我们要用的千帆。 pip install langchain-community # 安装百度千帆的官方 Python SDK pip install qianfan注意langchain和langchain-community的拆分是LangChain项目发展到一定阶段后的架构调整。核心库 (langchain) 包含最基础、最稳定的抽象和接口而各种模型的接入、工具链的集成等则放在社区库 (langchain-community) 中这样更利于生态的独立发展和版本管理。因此两者我们都需要安装。除了这些根据你的具体应用场景可能还需要其他工具文档加载器如果你要做RAG检索增强生成需要langchain-document-loaders或更具体的如pypdf读PDF、docx2txt读Word。向量数据库客户端如chromadb,faiss-cpu。环境变量管理使用python-dotenv来管理API密钥等敏感信息这是一个非常重要的安全实践。pip install python-dotenv2.2 获取千帆平台访问凭证应用的身份密钥要调用千帆的模型你需要一个“通行证”。这个通行证就是你的百度智能云账号下的API Key和Secret Key。注册与登录访问百度智能云官网完成实名认证并登录。开通千帆服务在控制台找到“千帆大模型平台”并开通。新用户通常有免费额度足够用于开发和测试。创建应用在千帆控制台进入“应用接入”-“创建应用”。填写应用名称等信息。获取密钥应用创建成功后在应用详情页你可以看到API Key和Secret Key。请立即妥善保存。安全须知这两个密钥等同于你的账号密码绝对不要直接硬编码在代码中更不要上传到GitHub等公开仓库。泄露可能导致资源被盗用和经济损失。正确的做法是使用环境变量。在项目根目录创建一个名为.env的文件注意前面的点内容如下QIANFAN_AK你的API_Key QIANFAN_SK你的Secret_Key然后在你的Python代码开头通过python-dotenv加载它们from dotenv import load_dotenv import os load_dotenv() # 加载 .env 文件中的所有变量 QIANFAN_AK os.getenv(QIANFAN_AK) QIANFAN_SK os.getenv(QIANFAN_SK) # 简单验证一下是否加载成功 if not QIANFAN_AK or not QIANFAN_SK: raise ValueError(请在 .env 文件中配置 QIANFAN_AK 和 QIANFAN_SK)2.3 开发工具推荐提升效率的利器一个好的IDE能极大提升开发效率。对于Python和AI开发我的首选是Visual Studio Code (VS Code)或PyCharm。VS Code轻量、插件生态丰富。必装插件Python、Pylance、Jupyter用于交互式实验。PyCharm功能更全面对Python项目管理和调试支持更好特别是专业版对科学计算和Web开发有深度集成。无论用哪个请确保配置好Python解释器路径指向你刚创建的虚拟环境venv_llm_app。这样IDE才能识别你安装的langchain和qianfan等包。3. LangChain核心概念与千帆SDK接入原理在开始写连接代码之前我们需要理解LangChain是如何思考问题的以及千帆SDK如何融入这个体系。这能让你在遇到问题时知道该从哪个层面去排查。3.1 LangChain的核心抽象像组装流水线LangChain将构建LLM应用的过程抽象为几个核心组件并通过“链”Chain将它们串联起来。你可以把它想象成一条智能流水线模型Models流水线的“核心处理器”。这就是LLM本身。LangChain定义了LLM纯文本模型和ChatModel对话模型等基础接口。我们的任务就是创建一个符合该接口的千帆模型实例。提示Prompts流水线的“输入模板和指令”。它负责将用户的原始输入、对话历史、上下文信息等按照一定格式组织成模型能更好理解的提示词。PromptTemplate是这里的关键。输出解析器Output Parsers流水线的“后处理模块”。模型产生的输出是原始文本我们需要将其解析成结构化的数据如Python对象、JSON等供程序使用。链Chains流水线的“传送带和装配逻辑”。它定义了上述组件组合和执行的顺序。最简单的LLMChain就是Prompt Model。更复杂的链可以包含条件判断、多步调用等。记忆Memory让流水线拥有“短期记忆”。用于在多轮对话中存储和回顾历史信息实现连贯的对话体验。代理Agents流水线的“智能调度中心”。它让模型能够自主决定何时、如何使用外部工具如搜索、计算、查数据库以完成复杂任务。对于我们当前“快速落地”的目标最需要掌握的就是Model、Prompt和Chain这三样。3.2 千帆SDK在LangChain中的角色实现接口的“适配器”千帆的Python SDK (qianfan) 提供了直接调用其模型服务的底层方法。但LangChain并不认识它。我们需要一个“适配器”这个适配器就是一个类它继承自LangChain的LLM或ChatModel基类然后在内部使用千帆SDK去完成实际的调用。好消息是langchain-community社区库已经为我们写好了这个适配器它位于langchain_community.llms和langchain_community.chat_models中。具体来说对于千帆我们主要使用QianfanLLMEndpoint用于文本补全类模型或更通用的、通过ChatQianfan来接入其对话模型。接入原理当我们实例化一个ChatQianfan对象时需要传入千帆的认证信息AK/SK和模型名称。这个对象内部已经实现了_generate等方法。当LangChain的链执行时会调用这个对象的生成方法该方法则通过千帆SDK向千帆平台发送HTTP请求获取模型响应再封装成LangChain标准的格式返回。模型选择千帆平台提供了多个模型例如ERNIE-Bot文心一言、ERNIE-Bot-turbo更快版本、ERNIE-Speed兼顾速度与效果、Llama-2-7b-chat、ChatGLM2-6B等。你可以在千帆控制台的“模型服务”页面查看所有可用模型及其对应的endpoint名称。在代码中我们通过model”模型名称”参数来指定。4. 三步实现基础对话功能理论说得再多不如一行代码。我们现在就来完成最核心的一步用LangChain调用千帆的模型实现一个简单的对话。4.1 第一步初始化千帆聊天模型首先在项目目录下创建一个Python文件比如basic_chat.py。# basic_chat.py from dotenv import load_dotenv from langchain_community.chat_models import QianfanChatEndpoint from langchain.schema import HumanMessage, SystemMessage # 1. 加载环境变量 load_dotenv() # 2. 初始化千帆聊天模型 # 注意这里是从 langchain_community 导入的 QianfanChatEndpoint chat QianfanChatEndpoint( modelERNIE-Bot-turbo, # 指定使用千帆平台上的 ERNIE-Bot-turbo 模型 # 以下参数会自动从环境变量 QIANFAN_AK 和 QIANFAN_SK 中读取 # 如果环境变量名不是这个可以显式传入 # qianfan_akos.getenv(YOUR_AK), # qianfan_skos.getenv(YOUR_SK), ) print(千帆聊天模型初始化成功)运行一下这个脚本如果没有报错说明你的环境配置和密钥都是正确的。LangChain社区库的QianfanChatEndpoint会自动查找名为QIANFAN_AK和QIANFAN_SK的环境变量。实操心得QianfanChatEndpoint这个类名可能会随着langchain-community的版本更新而变化。如果导入失败可以去官方文档或直接查看langchain_community/chat_models/qianfan.py的源码确认最新的类名。这是使用社区集成时常会遇到的小问题。4.2 第二步构建对话消息与调用LangChain遵循OpenAI的消息格式将对话中的每一条消息定义为一个带有role角色和content内容的对象。主要角色有SystemMessage: 系统消息用于设定AI助手的背景、角色或行为指令。HumanMessage: 用户人类发送的消息。AIMessage: AI助手回复的消息。我们来构建一个简单的对话# 接上面的代码 # 3. 构建消息列表 messages [ SystemMessage(content你是一个乐于助人且知识渊博的AI助手。), HumanMessage(content请用简单的语言解释一下什么是机器学习) ] # 4. 调用模型获取回复 print(正在向模型提问...) try: response chat.invoke(messages) # invoke 是同步调用方法 print(fAI回复: {response.content}) except Exception as e: print(f调用模型时出错: {e})运行这段代码你应该能看到千帆模型返回的关于机器学习的解释。chat.invoke(messages)是核心调用它接收一个消息列表返回一个AIMessage对象其content属性就是模型的文本回复。4.3 第三步使用LLMChain实现模板化对话直接调用invoke很灵活但当我们想复用相同的提示结构只替换其中部分内容时使用LLMChain会更方便。Chain将PromptTemplate和Model绑定在一起。# basic_chain.py from dotenv import load_dotenv from langchain_community.chat_models import QianfanChatEndpoint from langchain.prompts import ChatPromptTemplate from langchain.chains import LLMChain load_dotenv() # 1. 初始化模型同上 chat_model QianfanChatEndpoint(modelERNIE-Bot-turbo) # 2. 创建提示模板 # ChatPromptTemplate 用于构建对话式的提示 template ChatPromptTemplate.from_messages([ (system, 你是一位专业的{domain}专家。), (human, 请为以下概念提供一个简洁的定义{concept}) ]) # 3. 创建链 chain LLMChain(llmchat_model, prompttemplate) # 4. 运行链传入变量 result chain.invoke({domain: 计算机科学, concept: 神经网络}) print(f定义: {result[text]}) # LLMChain返回的结果字典中text键对应模型输出 # 可以轻松地复用链询问不同概念 result2 chain.invoke({domain: 金融学, concept: 量化宽松}) print(f定义: {result2[text]})在这个例子中{domain}和{concept}是模板中的变量。LLMChain的invoke方法接收一个包含这些变量的字典自动填充模板调用模型并返回结果。这种方式非常适合构建批量问答、内容生成等场景。5. 构建实用功能记忆、检索与流式输出基础对话跑通了但一个实用的应用需要更多能力。我们来看看如何为这个“流水线”增加记忆、知识库和更流畅的交互体验。5.1 为对话添加记忆Memory没有记忆的对话就像金鱼只有7秒。LangChain提供了多种记忆后端最简单常用的是ConversationBufferMemory它会在内存中保存最近的对话历史。# chat_with_memory.py from dotenv import load_dotenv from langchain_community.chat_models import QianfanChatEndpoint from langchain.chains import ConversationChain from langchain.memory import ConversationBufferMemory load_dotenv() # 初始化模型和记忆 llm QianfanChatEndpoint(modelERNIE-Bot-turbo, temperature0.7) # temperature控制创造性 memory ConversationBufferMemory() # 创建对话链它会自动处理记忆的保存和加载 conversation ConversationChain( llmllm, memorymemory, verboseTrue # 设置为True可以看到链的思考过程调试时非常有用 ) print(开始对话输入‘退出’结束) while True: user_input input(\n你: ) if user_input.lower() 退出: break # 调用链它会自动将当前输入和历史组合成提示 response conversation.predict(inputuser_input) print(fAI: {response}) # 注意predict方法会自动更新memory无需手动操作 # 对话结束后可以查看记忆内容 print(\n--- 本轮对话记忆 ---) print(memory.buffer)ConversationChain是一个高级链专门为多轮对话设计。verboseTrue会在控制台打印出链实际发送给模型的完整提示词这对于调试和理解模型行为至关重要。你会发现LangChain自动在提示词中加入了类似 “Previous conversation: …” 的部分这就是记忆在起作用。5.2 实现检索增强生成RAG雏形RAG是当前让LLM“拥有”特定知识、避免胡编乱造的核心技术。其核心思想是用户提问时先从你的知识库如文档、数据库中检索出相关片段然后将这些片段和问题一起交给模型让模型基于这些“证据”来回答。我们用最简单的本地文本向量化Embedding和检索来演示这个流程。这里需要安装额外的包pip install sentence-transformers chromadb# simple_rag.py from dotenv import load_dotenv from langchain_community.chat_models import QianfanChatEndpoint from langchain_community.embeddings import QianfanEmbeddingsEndpoint # 千帆的Embedding模型 from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.vectorstores import Chroma from langchain.chains import RetrievalQA load_dotenv() # 1. 准备知识库文本 knowledge_text LangChain是一个用于开发由语言模型驱动的应用程序的框架。 它提供了模块化的组件和链式调用的能力简化了构建复杂LLM应用的过程。 百度千帆大模型平台提供了包括文心一言在内的多种大模型服务。 通过千帆SDK开发者可以方便地调用这些模型。 # 2. 分割文本 text_splitter RecursiveCharacterTextSplitter( chunk_size200, # 每个片段的最大字符数 chunk_overlap50 # 片段之间的重叠字符数保持上下文连贯 ) texts text_splitter.split_text(knowledge_text) # 3. 使用千帆的Embedding模型将文本转换为向量 # 同样它会自动从环境变量读取AK/SK embeddings QianfanEmbeddingsEndpoint() # 4. 创建向量数据库这里使用内存型的Chroma vectorstore Chroma.from_texts(texts, embeddings) # 5. 创建检索器 retriever vectorstore.as_retriever(search_kwargs{k: 2}) # 检索最相关的2个片段 # 6. 初始化LLM llm QianfanChatEndpoint(modelERNIE-Bot-turbo) # 7. 创建检索问答链 qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, # 将检索到的所有文档“塞”进提示词 retrieverretriever, return_source_documentsTrue # 返回检索到的源文档便于验证 ) # 8. 提问 query 如何调用千帆平台上的模型 result qa_chain.invoke({query: query}) print(f问题: {query}) print(f回答: {result[result]}) print(\n--- 检索到的参考来源 ---) for doc in result[source_documents]: print(f- {doc.page_content[:100]}...) # 打印前100个字符这个例子虽然简单但完整展示了RAG的流水线加载-分割-向量化-存储-检索-生成。在实际项目中你可以将knowledge_text替换为从PDF、Word、网页爬取的大量文档构建一个强大的专属知识问答系统。5.3 启用流式输出Streaming对于需要长时间生成的回答让用户一个字一个字地看到输出体验远比等待很久后一次性显示全部要好。这就是流式输出。千帆SDK和LangChain都支持这一特性。# streaming_chat.py from dotenv import load_dotenv from langchain_community.chat_models import QianfanChatEndpoint from langchain.schema import HumanMessage load_dotenv() # 初始化模型时可以配置流式响应 chat QianfanChatEndpoint( modelERNIE-Bot-turbo, streamingTrue # 关键参数启用流式 ) # 构建一个需要较长思考的问题 prompt HumanMessage(content请详细阐述人工智能在未来教育领域的潜在应用场景分点说明。) print(AI正在思考并流式输出) print(- * 30) # 使用 stream 方法它会返回一个生成器 for chunk in chat.stream([prompt]): # chunk 是一个 AIMessageChunk 对象 if hasattr(chunk, content): print(chunk.content, end, flushTrue) # end 确保不换行flushTrue立即显示 print() # 最后换行 print(- * 30) print(回答完毕。)启用streamingTrue后调用chat.stream()会返回一个生成器。每次迭代得到一个AIMessageChunk包含模型刚生成的一小段文本。我们将其内容实时打印出来就实现了打字机效果。这在开发Web或桌面聊天应用时是必备功能。6. 工程化实践配置、优化与错误处理当应用从Demo走向生产我们需要考虑更多工程化问题如何管理配置如何优化性能与成本如何优雅地处理错误6.1 配置管理与参数调优硬编码参数是维护的噩梦。我们应该将可配置项集中管理。创建配置文件config.py# config.py import os from dotenv import load_dotenv load_dotenv() class Config: # 千帆认证 QIANFAN_AK os.getenv(QIANFAN_AK) QIANFAN_SK os.getenv(QIANFAN_SK) # 模型配置 DEFAULT_MODEL ERNIE-Bot-turbo # 备用模型当主模型不可用时切换 BACKUP_MODEL ERNIE-Speed # 生成参数对输出质量影响巨大 MODEL_TEMPERATURE 0.7 # 创造性0-1越高越随机 MODEL_TOP_P 0.8 # 核采样影响词汇选择的集中度 MODEL_MAX_TOKENS 2048 # 生成的最大token数控制回答长度 # RAG配置 CHUNK_SIZE 500 CHUNK_OVERLAP 100 RETRIEVE_K 3 # 每次检索的文档数量 # 系统提示词 SYSTEM_PROMPT 你是一个专业、准确、友好的AI助手。如果不知道答案请诚实地告知不要编造信息。然后在主程序中导入配置from config import Config from langchain_community.chat_models import QianfanChatEndpoint chat QianfanChatEndpoint( modelConfig.DEFAULT_MODEL, temperatureConfig.MODEL_TEMPERATURE, top_pConfig.MODEL_TOP_P, max_tokensConfig.MODEL_MAX_TOKENS, )关键参数解析temperature (温度)控制随机性。0非常确定倾向于选择最高概率的词输出稳定但可能枯燥。1非常随机富有创造性但可能不连贯。对于问答、总结建议0.3-0.7对于创意写作可以0.8-1.0。top_p (核采样)另一种控制随机性的方式。它从累积概率超过p的最小词集中采样。通常与temperature二选一进行调整。0.8-0.95是常用范围。max_tokens (最大令牌数)限制单次生成的长度。需结合模型上下文窗口设置如千帆ERNIE-Bot-turbo上下文约8K tokens。设置过小可能导致回答被截断。实操心得参数没有“最佳值”只有“最适合当前任务的组合”。务必通过A/B测试来调整。例如做一个摘要任务可以固定问题分别用temperature0.3和0.7生成结果人工评估哪个更简洁、准确。6.2 性能与成本考量缓存对于重复或相似的查询使用缓存可以极大减少API调用次数和响应时间。LangChain内置了InMemoryCache、SQLiteCache等。from langchain.cache import InMemoryCache from langchain.globals import set_llm_cache set_llm_cache(InMemoryCache()) # 设置全局LLM缓存首次查询后相同的提示词会直接从缓存返回结果。异步调用如果你的应用是Web服务需要同时处理多个用户请求使用异步IO可以大幅提升吞吐量。LangChain支持异步接口。import asyncio async def async_chat(): chat QianfanChatEndpoint(modelERNIE-Bot-turbo) messages [HumanMessage(content你好)] response await chat.ainvoke(messages) # 注意是 ainvoke print(response.content) asyncio.run(async_chat())成本监控千帆平台有详细的用量统计和计费说明。在代码关键位置记录每次调用的模型、token消耗请求响应有助于分析成本构成。千帆SDK的响应对象中可能包含usage信息可以记录下来。6.3 健壮性提升错误处理与重试网络请求、模型服务都可能出现临时故障。一个健壮的应用必须有完善的错误处理机制。# robust_chat.py import time from typing import Optional from dotenv import load_dotenv from langchain_community.chat_models import QianfanChatEndpoint from langchain.schema import HumanMessage from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type import openai # 导入此模块是为了捕获其错误类型千帆SDK可能使用类似结构 load_dotenv() class RobustQianfanChat: def __init__(self, primary_model: str, backup_model: str): self.primary_model primary_model self.backup_model backup_model self._init_clients() def _init_clients(self): 初始化主备客户端 self.primary_client QianfanChatEndpoint(modelself.primary_model) self.backup_client QianfanChatEndpoint(modelself.backup_model) retry( stopstop_after_attempt(3), # 最多重试3次 waitwait_exponential(multiplier1, min2, max10), # 指数退避等待 retryretry_if_exception_type((openai.APIError, openai.APITimeoutError)), # 重试特定错误 reraiseTrue # 重试次数用尽后抛出原始异常 ) def _call_with_retry(self, client, messages): 带重试机制的调用 return client.invoke(messages) def chat(self, message: str) - Optional[str]: 健壮的聊天方法支持主备切换和重试 messages [HumanMessage(contentmessage)] last_error None # 先尝试主模型 for client_name, client in [(主模型, self.primary_client), (备用模型, self.backup_client)]: try: print(f正在尝试使用 {client_name} 调用...) response self._call_with_retry(client, messages) print(f{client_name} 调用成功。) return response.content except Exception as e: print(f{client_name} 调用失败: {type(e).__name__}: {e}) last_error e time.sleep(1) # 切换前短暂等待 continue # 尝试备用模型 # 所有尝试都失败 print(所有模型调用均失败。) # 这里可以记录更详细的错误日志或触发告警 raise last_error if last_error else Exception(未知错误) # 使用示例 if __name__ __main__: assistant RobustQianfanChat(primary_modelERNIE-Bot-turbo, backup_modelERNIE-Speed) try: answer assistant.chat(今天的天气怎么样) print(f回答: {answer}) except Exception as e: print(f对话最终失败: {e})这个类做了几件事主备切换如果主模型调用失败自动尝试备用模型。自动重试使用tenacity库为每次调用添加重试逻辑应对网络抖动或服务端临时过载。错误隔离将可能失败的调用封装起来避免一个请求失败导致整个服务崩溃。注意事项重试策略需要谨慎设计。对于因用户输入不当导致的错误如触发内容安全策略重试是没有意义的反而会增加成本。最好能根据错误类型进行区分处理。千帆SDK返回的错误通常会有明确的错误码可以根据这些错误码决定是重试、降级还是直接给用户返回友好提示。7. 从脚本到服务构建一个简单的Web API一个真正的“应用”通常需要提供API接口。我们用轻量级的FastAPI框架快速将我们的LLM能力包装成一个Web服务。安装依赖pip install fastapi uvicorn创建app.py# app.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from typing import Optional import uvicorn from dotenv import load_dotenv # 导入我们之前写好的健壮聊天类 from robust_chat import RobustQianfanChat # 假设 robust_chat.py 在同一目录 load_dotenv() app FastAPI(title千帆LLM应用API, description基于LangChain和千帆的AI服务接口) # 初始化聊天引擎 chat_engine RobustQianfanChat(primary_modelERNIE-Bot-turbo, backup_modelERNIE-Speed) # 定义请求和响应模型 class ChatRequest(BaseModel): message: str user_id: Optional[str] None # 可用于区分用户实现隔离的记忆 class ChatResponse(BaseModel): success: bool reply: Optional[str] None error: Optional[str] None app.get(/) def read_root(): return {status: online, service: Qianfan LLM API} app.post(/chat, response_modelChatResponse) async def chat_endpoint(request: ChatRequest): 核心聊天接口。 if not request.message or request.message.strip() : raise HTTPException(status_code400, detail消息内容不能为空) try: # 这里可以扩展根据 user_id 从数据库加载对应的记忆ConversationBufferMemory # 目前我们先使用无记忆的简单调用 reply chat_engine.chat(request.message) return ChatResponse(successTrue, replyreply) except Exception as e: # 记录详细日志到文件或监控系统 print(fAPI处理请求时出错: {e}) return ChatResponse( successFalse, errorf服务暂时不可用请稍后重试。, replyNone ) if __name__ __main__: # 启动服务监听本地 8000 端口 uvicorn.run(app, host0.0.0.0, port8000)运行这个服务python app.py然后你就可以通过HTTP请求与你的LLM应用交互了# 使用 curl 测试 curl -X POST http://127.0.0.1:8000/chat \ -H Content-Type: application/json \ -d {message: 你好请介绍一下你自己, user_id: test_user_001}这个简单的API服务已经具备了核心功能。你可以在此基础上轻松扩展添加记忆在chat_engine外层包裹一个字典以user_id为键为每个用户存储独立的ConversationChain。添加流式响应将端点改为返回StreamingResponse并调用模型的stream方法。添加鉴权使用FastAPI的依赖项系统为接口添加API Key验证。添加限流使用slowapi等中间件防止滥用。8. 常见问题与排查技巧实录在实际开发和部署中你几乎一定会遇到下面这些问题。这里记录了我踩过的坑和解决方法。8.1 认证与连接失败问题现象初始化QianfanChatEndpoint时抛出认证错误如AuthenticationError或PermissionDeniedError。排查步骤检查环境变量确认.env文件在正确的工作目录且变量名是QIANFAN_AK和QIANFAN_SK。可以在Python中print(os.getenv(“QIANFAN_AK”))看看是否为None。检查密钥有效性登录千帆控制台确认应用状态正常API Key和Secret Key是否复制正确注意不要有多余空格。检查网络连通性确保你的服务器或开发机可以访问千帆的API端点。可以尝试用ping命令或curl测试网络。检查额度在千帆控制台查看该应用的调用额度是否已用尽或未开通付费。8.2 模型响应慢或超时问题现象调用invoke后长时间无响应最终超时。可能原因与解决提示词过长如果传入的上下文如记忆历史或检索到的文档非常长模型需要更长的处理时间。尝试减少max_tokens或使用更高效的文本分割策略减少输入token数。模型负载公开的云服务在高峰时段可能出现排队。可以在代码中设置更长的超时参数如果SDK支持。实现前面提到的重试与退避机制。考虑使用streamingTrue流式响应有时能更快地获得首字。本地网络问题检查本地网络是否稳定。8.3 模型输出不符合预期问题现象回答跑偏、胡言乱语、格式错误。调试方法开启Verbose模式在初始化LLMChain或ConversationChain时设置verboseTrue。这会在控制台打印出实际发送给模型的完整提示词。这是最重要的调试手段很多时候问题出在提示词的组装上。检查系统提示词系统提示词对模型行为有决定性影响。确保你的SystemMessage清晰、明确地定义了AI的角色和任务边界。调整生成参数降低temperature如设为0.3会让输出更稳定、更可预测。对于需要严格格式的输出如JSON可以将temperature设为0。使用输出解析器对于需要结构化输出的场景不要依赖模型自由发挥。使用LangChain的PydanticOutputParser或StructuredOutputParser在提示词中明确告诉模型需要返回的格式并用解析器来校验和提取。8.4 LangChain版本兼容性问题问题现象代码在更新LangChain库后突然报错提示某个类或函数不存在。应对策略锁定版本在生产环境中在requirements.txt中严格锁定关键库的版本例如langchain0.1.0。查看更新日志升级前务必查看LangChain和langchain-community的GitHub Release Notes了解破坏性变更。社区集成路径变化langchain-community的集成模块路径可能会变。如果导入失败去官方文档或GitHub仓库的对应目录下查看最新的导入语句。8.5 处理长上下文与Token限制问题现象当对话历史或检索到的文档总长度超过模型上下文窗口如8K时调用会失败。解决方案摘要式记忆不要无限制地保存所有对话历史。使用ConversationSummaryMemory或ConversationSummaryBufferMemory它们会定期将长历史总结成一段摘要从而节省token。滑动窗口只保留最近N轮对话。智能检索在RAG中确保你的检索器只返回最相关的几个片段search_kwargs{“k”: 3}而不是所有相关文档。模型选择对于超长文本处理可以考虑千帆平台上支持更长上下文如128K的特定模型。8.6 内容安全与审核问题现象某些用户输入或模型输出触发了千帆平台的内容安全策略返回相关错误。处理建议前置过滤在应用层对用户输入进行初步的关键词过滤或敏感词检测。友好提示捕获千帆返回的内容安全错误给用户一个友好的提示如“您的问题可能涉及敏感内容请重新表述”。后置审核对于生成的内容尤其是面向公众的可以考虑接入额外的审核API进行二次检查。走到这一步你已经拥有了一个功能相对完整、具备一定健壮性的LLM应用原型。它从最初简单的模型调用演进成了包含配置管理、错误处理、记忆功能甚至对外提供API服务的系统。这个过程中LangChain提供的抽象让我们能专注于业务逻辑的组装而千帆SDK则提供了稳定可靠的大模型能力供给。