第三方框架接入

LangChain、LiteLLM 等多供应方框架如何把灵渠作为统一入口接入——配置示例、跨供应方在框架内的切换、自定义头、嵌入与差异提示

LangChain、LiteLLM 等开源框架本身已提供多供应方抽象与链式编排能力。把灵渠作为这些框架的统一入口，等于在客户既有编排之上再叠加一层企业级治理——智能路由、缓存检查点、安全护栏、统一计量计费与多上游聚合——而框架内的链路与切换逻辑无需改动。

统一入口前缀： /v1/*（数据平面）。下文示例中的 <平台入口地址> 请替换为你的平台实例统一入口地址。

接入原则。 框架负责客户侧的编排与多供应方抽象，灵渠负责统一治理与上游择优。把框架内各供应方客户端的基址都指向灵渠后，框架原有的"切换供应方"动作即转化为灵渠模型池内的统一中性名切换，治理与计量在灵渠侧统一完成。

1. LangChain 接入

LangChain 的各 Chat 模型类都允许覆写基址。以 OpenAI 兼容形态为例，把基址指向灵渠即可：

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

# 把 LangChain 客户端指向灵渠
llm = ChatOpenAI(
    model="<上游模型中性名>",
    base_url="<平台入口地址>/v1",
    api_key="tsxt-************************"  # 灵渠 API 密钥
)

response = llm.invoke([HumanMessage(content="你好，帮我提炼这段需求的核心目标。")])
print(response.content)

import { ChatOpenAI } from "@langchain/openai";

// 把 LangChain 客户端指向灵渠
const llm = new ChatOpenAI({
  model: "<上游模型中性名>",
  configuration: { baseURL: "<平台入口地址>/v1" },
  apiKey: "tsxt-************************", // 灵渠 API 密钥
});

const response = await llm.invoke("你好，帮我提炼这段需求的核心目标。");
console.log(response.content);

框架内的供应方切换

LangChain 原有的"按供应方建多个客户端"写法在接入灵渠后照常工作——把每个客户端的基址都指向灵渠，模型名换成灵渠统一中性名，由灵渠按路由择优转发即可：

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

base_url = "<平台入口地址>/v1"

# 同一入口，按业务用途建多个中性名客户端
fast_llm = ChatOpenAI(model="<轻量模型中性名>", base_url=base_url,
                      api_key="tsxt-************************")
strong_llm = ChatOpenAI(model="<旗舰模型中性名>", base_url=base_url,
                        api_key="tsxt-************************")

draft = fast_llm.invoke([HumanMessage(content="先草拟一版要点。")])
final = strong_llm.invoke([HumanMessage(content="据此完善为正式表述。")])

在 LangChain 内是否显式区分"轻量"与"旗舰"客户端取决于编排需要；即便全部填同一个中性名，灵渠也会按请求复杂度自动研判并择优转发。两种做法可并存。

自定义头与嵌入

LangChain 各 Chat 模型类对自定义头的参数名略有差异，常见以 default_headers 传入：

llm = ChatOpenAI(
    model="<上游模型中性名>",
    base_url="<平台入口地址>/v1",
    api_key="tsxt-************************",
    default_headers={ "x-lq-trace-id": "<客户侧自定义追踪标识>" }
)

若需经灵渠生成嵌入（用于语义相似度匹配等下游用途），可使用 LangChain 的嵌入类并把基址指向灵渠：

from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(
    model="<嵌入模型中性名>",
    base_url="<平台入口地址>/v1",
    api_key="tsxt-************************"
)

vec = embeddings.embed_query("一段待匹配的文本")
docs = embeddings.embed_documents(["候选片段一", "候选片段二"])

不同框架的嵌入类对入参格式（文本字符串 / 数值数组）处理不一，跨供应方使用时请以接收文本字符串的嵌入类为准，以保证在灵渠多上游聚合下的一致性。嵌入向量在客户侧用于语义相似度匹配，灵渠仅负责生成与计量。

2. LiteLLM 接入

LiteLLM 同样自带多供应方抽象。把 base_url 指向灵渠、模型名换成统一中性名即可：

from litellm import completion

response = completion(
    model="<上游模型中性名>",
    messages=[{"role": "user", "content": "你好，帮我归纳这份纪要的结论。"}],
    base_url="<平台入口地址>/v1",
    api_key="tsxt-************************"  # 灵渠 API 密钥
)

print(response.choices[0].message.content)

自定义头经 extra_headers 传入：

response = completion(
    model="<上游模型中性名>",
    messages=[{"role": "user", "content": "你好。"}],
    base_url="<平台入口地址>/v1",
    api_key="tsxt-************************",
    extra_headers={ "x-lq-trace-id": "<客户侧自定义追踪标识>" }
)

LiteLLM 原有的多供应方调用写法在接入灵渠后保持不变——基址统一指向灵渠，供应方差异由灵渠在内部聚合与路由层消化，客户侧只见统一中性名。

3. 框架接入的兼容边界

第三方框架接入只在框架支持且灵渠核心支持的能力交集内生效。接入前请留意：

提示	说明
能力取交集	仅当框架与灵渠都支持某能力时，该能力才能经接入透传；框架特有但灵渠未覆盖的供应方或参数可能不生效
模型名用中性名	框架内各客户端的模型名一律填灵渠统一中性名，勿填某家供应方私有名
基址统一指向灵渠	框架内所有供应方客户端的基址都改指 `<平台入口地址>/v1`，由灵渠统一聚合
计量统一在灵渠侧	不论框架内如何切换，计量与用量明细均由灵渠按统一计价词元口径逐条落账
嵌入入参格式	跨供应方使用嵌入时优先选接收文本字符串的嵌入类，避免数值数组入参的供应方兼容问题

1. LangChain 接入

框架内的供应方切换

自定义头与嵌入

2. LiteLLM 接入

3. 框架接入的兼容边界

相关链接

On this page