langchain-dependencies

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

关键原则：

• LangChain 1.0 是当前的长期支持（LTS）版本。 新项目始终从 1.0+ 开始。LangChain 0.3 仅提供旧版维护，不要用于新项目。
• langchain-core 是共享基础：始终与其他包一同显式安装。
• langchain-community（仅限 Python）不遵循语义化版本控制；请谨慎锁定版本。
• LangGraph 与 Deep Agents： 根据用例选择一种编排方式——它们是替代方案，并非必需搭配的技术栈（请参阅下文的框架选择）。
• Provider 集成（模型、向量存储、工具）需单独安装，这样只需引入实际使用的部分。

---

环境要求

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

---

核心包

Python — 始终必需

包	作用	最低版本
langchain	Agent、链、检索	1.0
langchain-core	基础类型和接口（peer dep）	1.0
langsmith	跟踪、评估、数据集	0.3.0

Python — 编排（任选其一）

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

Python — 模型 Provider（选择你使用的包）

包	Provider
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 工作区和 monorepo 中——它是一个对等依赖，不一定会自动提升安装。

---

最简项目模板

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

</python>
</ex-langgraph-python>

<ex-langgraph-typescript>
<typescript>
LangGraph 项目的最简 package.json 依赖（与提供商无关）。
```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

</python>
</ex-deepagents-python>

<ex-deepagents-typescript>
<typescript>
Deep Agents 项目的最简 package.json 依赖（与提供商无关）。
```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.

</python>
</ex-with-tools-python>

<ex-with-tools-typescript>
<typescript>
为 LangGraph 项目添加 Tavily 搜索和向量存储。
```json
{
  "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_TRACING=true
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

</fix-legacy-version>

<fix-community-unpinned>
`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 集成）。
</fix-community-unpinned>

<fix-community-tool-outdated>
像 `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

</fix-community-tool-outdated>

<fix-community-import-deprecated>
许多过去属于 `langchain-community` 的工具现在都有了专用软件包，并更新了导入路径。请始终优先使用专用软件包的导入方式。

```python
# 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 中。 ```json // 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" } }

</typescript>
</fix-core-not-installed>

<fix-python-version>
<python>
LangChain 1.0 不支持 Python 3.9 及更低版本。
```python
# Verify before installing
import sys
assert sys.version_info >= (3, 10), "Python 3.10+ required for LangChain 1.0"

官方不支持低于 20 的 Node.js 版本。 ```bash # Verify before installing node --version # must be v20.x or higher ```