langchain-dependencies

LangChain 生态由多个专注于不同领域、独立发布版本的程序包组成。了解你需要哪些程序包及其版本约束，可以避免不兼容问题，并让升级更可预测。

核心原则：

• LangChain 1.0 是当前的 LTS 版本。 新项目始终从 1.0+ 开始。LangChain 0.3 仅提供旧版维护支持——不要将其用于新项目。
• langchain-core 是共享基础：安装任何其他程序包时，都要同时显式安装它。
• langchain-community（仅限 Python）不遵循语义化版本规范；请谨慎固定其版本。
• LangGraph 与 Deep Agents： 根据使用场景选择一种编排方式——它们是替代方案，并非必须同时使用的技术栈（参见下文的框架选择）。
• 提供商集成（模型、向量存储、工具）需单独安装，这样你只需引入实际使用的内容。

---

环境要求

要求	Python	TypeScript / Node
最低运行时版本	Python 3.10+	Node.js 20+
LangChain	1.0+（LTS）	1.0+（LTS）
LangSmith SDK	>= 0.3.0	>= 0.3.0

---

框架选择

选择**一种** Agent 编排层即可，无需同时使用两者。

框架	适用场景	核心附加程序包
LangGraph	需要精细控制图、自定义工作流、循环或分支	langgraph / @langchain/langgraph
Deep Agents	希望开箱即用地获得完整的规划、记忆、文件上下文和技能	deepagents（依赖 LangGraph；会将其作为传递依赖安装）

两者都基于 langchain + langchain-core + langsmith。

---

核心程序包

Python — 始终必需

程序包	作用	最低版本
langchain	Agent、链、检索	1.0
langchain-core	基础类型与接口（对等依赖）	1.0
langsmith	跟踪、评估、数据集	0.3.0

Python — 编排（选择一个）

程序包	适用场景	最低版本
langgraph	直接构建自定义图	1.0
deepagents	使用 Deep Agents 框架	最新版

Python — 模型提供商（选择你要使用的程序包）

程序包	提供商
langchain-openai	OpenAI（GPT-4o、o3、……）
langchain-anthropic	Anthropic（Claude）
langchain-google-genai	Google（Gemini）
langchain-mistralai	Mistral
langchain-groq	Groq（快速推理）
langchain-cohere	Cohere
langchain-fireworks	Fireworks AI
langchain-together	Together AI
langchain-huggingface	Hugging Face Hub
langchain-ollama	Ollama（本地模型）
langchain-aws	AWS Bedrock
langchain-azure-ai	Azure AI Foundry

Python — 常用工具和检索包

这些包对兼容性的要求更严格——除非有特定原因，否则请使用最新可用版本。

包	功能	说明
langchain-tavily	Tavily 网页搜索（TavilySearch）	专用集成包；优先使用最新版本
langchain-text-splitters	文本分块工具	遵循语义化版本控制，请保持更新
langchain-community	1000 多种集成（备用）	不遵循语义化版本控制——请固定在次版本系列
faiss-cpu	FAISS 向量存储（本地）	通过 langchain-community 使用；请使用最新版本
langchain-chroma	Chroma 向量存储	专用集成包；优先使用最新版本
langchain-pinecone	Pinecone 向量存储	专用集成包；优先使用最新版本
langchain-qdrant	Qdrant 向量存储	专用集成包；优先使用最新版本
langchain-weaviate	Weaviate 向量存储	专用集成包；优先使用最新版本
langsmith[pytest]	LangSmith 的 pytest 插件	需要 langsmith >= 0.3.4

langchain-community 稳定性说明： 此包不遵循语义化版本控制。次版本发布可能包含破坏性变更。若有专用集成包（例如 langchain-chroma、langchain-tavily），请优先使用——它们独立进行版本管理，稳定性更高。

TypeScript — 必需

包	用途	最低版本
@langchain/core	基础类型和接口（对等依赖）	1.0
langchain	Agent、链、检索	1.0
langsmith	跟踪、评估、数据集	0.3.0

TypeScript — 编排（任选其一）

包	适用场景	最低版本
@langchain/langgraph	直接构建自定义图	1.0
deepagents	使用 Deep Agents 框架	最新版本

TypeScript — 模型提供商（选择所用的一个或多个）

包	提供商
@langchain/openai	OpenAI（GPT-4o、o3、…）
@langchain/anthropic	Anthropic（Claude）
@langchain/google-genai	Google（Gemini）
@langchain/mistralai	Mistral
@langchain/groq	Groq（快速推理）
@langchain/cohere	Cohere
@langchain/aws	AWS Bedrock
@langchain/azure-openai	Azure OpenAI
@langchain/ollama	Ollama（本地模型）

TypeScript — 常用工具和检索包

包	功能	说明
@langchain/tavily	Tavily 网页搜索（TavilySearch）	专用集成包；优先使用最新版本
@langchain/community	多种社区集成	谨慎使用；优先选择专用包
@langchain/pinecone	Pinecone 向量存储	专用集成包；优先使用最新版本
@langchain/qdrant	Qdrant 向量存储	专用集成包；优先使用最新版本
@langchain/weaviate	Weaviate 向量存储	专用集成包；优先使用最新版本

必须显式安装 @langchain/core，尤其是在 yarn 工作区和单仓库中——它是一个对等依赖，不一定会自动提升到顶层。

---

最小项目模板

LangGraph 项目的最小依赖集（与模型提供商无关）。

# requirements.txt
langchain>=1.0,<2.0
langchain-core>=1.0,<2.0
langgraph>=1.0,<2.0
langsmith>=0.3.0

# Add your model provider, e.g.:
# langchain-openai
# langchain-anthropic
# langchain-google-genai

LangGraph 项目的最小 package.json 依赖项（与模型提供商无关）。

{
  "dependencies": {
    "@langchain/core": "^1.0.0",
    "langchain": "^1.0.0",
    "@langchain/langgraph": "^1.0.0",
    "langsmith": "^0.3.0"
  }
}

Deep Agents 项目的最小依赖集（与模型提供商无关）。

# requirements.txt
deepagents            # bundles langgraph internally
langchain>=1.0,<2.0
langchain-core>=1.0,<2.0
langsmith>=0.3.0

# Add your model provider, e.g.:
# langchain-anthropic
# langchain-openai

Deep Agents 项目的最小 package.json 依赖项（与模型提供商无关）。

{
  "dependencies": {
    "deepagents": "latest",
    "@langchain/core": "^1.0.0",
    "langchain": "^1.0.0",
    "langsmith": "^0.3.0"
  }
}

为 LangGraph 项目添加 Tavily 搜索和向量存储。

# requirements.txt
langchain>=1.0,<2.0
langchain-core>=1.0,<2.0
langgraph>=1.0,<2.0
langsmith>=0.3.0

# Web search
langchain-tavily          # use latest; partner package, semver

# Vector store — pick one:
langchain-chroma          # use latest; partner package, semver
# langchain-pinecone      # use latest; partner package, semver
# langchain-qdrant        # use latest; partner package, semver

# Text processing
langchain-text-splitters  # use latest; semver

# Your model provider:
# langchain-openai / langchain-anthropic / etc.

为 LangGraph 项目添加 Tavily 搜索和向量存储。

{
  "dependencies": {
    "@langchain/core": "^1.0.0",
    "langchain": "^1.0.0",
    "@langchain/langgraph": "^1.0.0",
    "langsmith": "^0.3.0",
    "@langchain/tavily": "latest",
    "@langchain/pinecone": "latest"
  }
}

---

版本策略与升级方案

包组	版本策略	安全升级策略
langchain、langchain-core	严格遵循语义化版本（1.0 LTS）	允许次要版本升级：>=1.0,<2.0
langgraph / @langchain/langgraph	严格遵循语义化版本（v1 LTS）	允许次要版本升级：>=1.0,<2.0
langsmith	严格遵循语义化版本	允许次要版本升级：>=0.3.0
专用集成包（例如 langchain-tavily、langchain-chroma）	独立版本管理	允许次要版本升级；使用最新版本
langchain-community	不遵循语义化版本	固定精确的次要版本：>=0.4.0,<0.5.0
deepagents	遵循项目发布版本	在生产环境中固定为经过测试的版本

所有遵循语义化版本的包，仅会在主版本升级时发生破坏性变更（1.x → 2.x）。在整个 1.x 系列中，已弃用的功能仍可使用，但会发出警告。

优先使用专用集成包，而非 langchain-community。 如果存在专用包（例如，使用 langchain-chroma，而非 langchain-community 中的 Chroma 集成），请使用专用包——专用包独立管理版本，且经过了更充分的测试。

社区工具包（Tavily、向量存储等）应保持为最新版本，除非项目需要锁定环境。这些包通常会随着 LangChain/LangGraph 更新频繁发布兼容性修复。

---

环境变量

所有密钥都会在运行时从环境中读取。只设置你实际使用的服务所需的密钥。

# LangSmith (always recommended for observability)
LANGSMITH_API_KEY=<your-key>
LANGSMITH_PROJECT=<project-name>   # optional, defaults to "default"

# Model provider — set the one(s) you use
OPENAI_API_KEY=<your-key>
ANTHROPIC_API_KEY=<your-key>
GOOGLE_API_KEY=<your-key>
MISTRAL_API_KEY=<your-key>
GROQ_API_KEY=<your-key>
COHERE_API_KEY=<your-key>
FIREWORKS_API_KEY=<your-key>
TOGETHER_API_KEY=<your-key>
HUGGINGFACEHUB_API_TOKEN=<your-key>

# Common tool/retrieval services
TAVILY_API_KEY=<your-key>          # for Tavily search
PINECONE_API_KEY=<your-key>        # for Pinecone

---

常见错误

不要使用 LangChain 0.3 启动新项目。该版本仅提供维护支持，直至 2026 年 12 月。

# WRONG: legacy, no new features, security patches only
langchain>=0.3,<0.4

# CORRECT: LangChain 1.0 LTS
langchain>=1.0,<2.0

`langchain-community` 在次要版本升级时可能会出现问题——它不遵循语义化版本规范。

# WRONG: allows minor-version updates that may be breaking
langchain-community>=0.4

# CORRECT: pin to exact minor series
langchain-community>=0.4.0,<0.5.0

如果存在等效的专用集成包，也请考虑切换到该包（例如，使用 langchain-chroma，而不是社区 Chroma 集成）。

`langchain-tavily` 等社区工具包和向量存储集成会随 LangChain 更新发布兼容性修复。使用旧的固定版本可能导致导入错误或工具架构损坏。

# RISKY: old pin may be incompatible with LangChain 1.0
langchain-tavily==0.0.1

# BETTER: allow latest within the current major
langchain-tavily>=0.1

许多过去位于 `langchain-community` 中的工具现在都有专用包，并使用更新后的导入路径。请始终优先使用专用包导入。

# WRONG — deprecated community import path
from langchain_community.tools.tavily_search import TavilySearchResults
from langchain_community.tools import WikipediaQueryRun
from langchain_community.vectorstores import Chroma
from langchain_community.vectorstores import Pinecone

# CORRECT — use dedicated package imports
from langchain_tavily import TavilySearch                  # pip: langchain-tavily (TavilySearchResults is deprecated)
from langchain_community.tools import WikipediaQueryRun  # no dedicated pkg yet
from langchain_chroma import Chroma                       # pip: langchain-chroma
from langchain_pinecone import PineconeVectorStore        # pip: langchain-pinecone

要查找任何集成当前的规范导入方式，请搜索集成目录： https://python.langchain.com/docs/integrations/tools/

每个条目都会列出正确的包和导入路径。如果存在专用包，请使用该包——社区路径可能仍可用，但已被视为旧版路径。

`@langchain/core` 是一个对等依赖项——必须将其添加到 package.json 中，尤其是在 monorepo 中。

// WRONG: missing @langchain/core (breaks in yarn workspaces / strict hoisting)
{
  "dependencies": {
    "@langchain/langgraph": "^1.0.0"
  }
}

// CORRECT: always list @langchain/core explicitly
{
  "dependencies": {
    "@langchain/core": "^1.0.0",
    "@langchain/langgraph": "^1.0.0"
  }
}

LangChain 1.0 不支持 Python 3.9 及更低版本。

# Verify before installing
import sys
assert sys.version_info >= (3, 10), "Python 3.10+ required for LangChain 1.0"

Node.js 20 以下版本不受官方支持。

# Verify before installing
node --version   # must be v20.x or higher