> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Nebius 集成

> 使用 LangChain Python 与 Nebius 检索器集成。

`NebiusRetriever` 支持使用来自 [Nebius Token Factory](https://tokenfactory.nebius.com/) 的嵌入向量进行高效的相似性搜索。它利用高质量的嵌入模型来实现文档的语义搜索。

此检索器针对需要对文档集合执行相似性搜索，但无需将向量持久化到向量数据库的场景进行了优化。它使用矩阵操作在内存中执行向量相似性搜索，因此对于中等规模的文档集合非常高效。

## 设置

### 安装

Nebius 集成可以通过 pip 安装：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pip install -U langchain-nebius
```

### 凭证

Nebius 需要一个 API 密钥，可以作为初始化参数 `api_key` 传递，或设置为环境变量 `NEBIUS_API_KEY`。您可以通过在 [Nebius Token Factory](https://tokenfactory.nebius.com/) 上创建账户来获取 API 密钥。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import getpass
import os

# 确保您已将 API 密钥设置为环境变量
if "NEBIUS_API_KEY" not in os.environ:
    os.environ["NEBIUS_API_KEY"] = getpass.getpass("Enter your Nebius API key: ")
```

## 实例化

`NebiusRetriever` 需要一个 `NebiusEmbeddings` 实例和一个文档列表。以下是初始化方法：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_core.documents import Document
from langchain_nebius import NebiusEmbeddings, NebiusRetriever

# 创建示例文档
docs = [
    Document(
        page_content="Paris is the capital of France", metadata={"country": "France"}
    ),
    Document(
        page_content="Berlin is the capital of Germany", metadata={"country": "Germany"}
    ),
    Document(
        page_content="Rome is the capital of Italy", metadata={"country": "Italy"}
    ),
    Document(
        page_content="Madrid is the capital of Spain", metadata={"country": "Spain"}
    ),
    Document(
        page_content="London is the capital of the United Kingdom",
        metadata={"country": "UK"},
    ),
    Document(
        page_content="Moscow is the capital of Russia", metadata={"country": "Russia"}
    ),
    Document(
        page_content="Washington DC is the capital of the United States",
        metadata={"country": "USA"},
    ),
    Document(
        page_content="Tokyo is the capital of Japan", metadata={"country": "Japan"}
    ),
    Document(
        page_content="Beijing is the capital of China", metadata={"country": "China"}
    ),
    Document(
        page_content="Canberra is the capital of Australia",
        metadata={"country": "Australia"},
    ),
]

# 初始化嵌入模型
embeddings = NebiusEmbeddings()

# 创建检索器
retriever = NebiusRetriever(
    embeddings=embeddings,
    docs=docs,
    k=3,  # 返回的文档数量
)
```

## 用法

### 检索相关文档

您可以使用检索器查找与查询相关的文档：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 查询欧洲首都
query = "What are some capitals in Europe?"
results = retriever.invoke(query)

print(f"Query: {query}")
print(f"Top {len(results)} results:")
for i, doc in enumerate(results):
    print(f"{i + 1}. {doc.page_content} (Country: {doc.metadata['country']})")
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Query: What are some capitals in Europe?
Top 3 results:
1. Paris is the capital of France (Country: France)
2. Berlin is the capital of Germany (Country: Germany)
3. Rome is the capital of Italy (Country: Italy)
```

### 使用 get\_relevant\_documents

您也可以直接使用 `get_relevant_documents` 方法（尽管 `invoke` 是首选接口）：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 查询亚洲国家
query = "What are the capitals in Asia?"
results = retriever.get_relevant_documents(query)

print(f"Query: {query}")
print(f"Top {len(results)} results:")
for i, doc in enumerate(results):
    print(f"{i + 1}. {doc.page_content} (Country: {doc.metadata['country']})")
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Query: What are the capitals in Asia?
Top 3 results:
1. Beijing is the capital of China (Country: China)
2. Tokyo is the capital of Japan (Country: Japan)
3. Canberra is the capital of Australia (Country: Australia)
```

### 自定义结果数量

您可以在查询时通过传递 `k` 参数来调整结果数量：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 查询特定国家，自定义 k 值
query = "Where is France?"
results = retriever.invoke(query, k=1)  # 覆盖默认的 k 值

print(f"Query: {query}")
print(f"Top {len(results)} result:")
for i, doc in enumerate(results):
    print(f"{i + 1}. {doc.page_content} (Country: {doc.metadata['country']})")
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Query: Where is France?
Top 1 result:
1. Paris is the capital of France (Country: France)
```

### 异步支持

NebiusRetriever 支持异步操作：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import asyncio


async def retrieve_async():
    query = "What are some capital cities?"
    results = await retriever.ainvoke(query)

    print(f"Async query: {query}")
    print(f"Top {len(results)} results:")
    for i, doc in enumerate(results):
        print(f"{i + 1}. {doc.page_content} (Country: {doc.metadata['country']})")


await retrieve_async()
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Async query: What are some capital cities?
Top 3 results:
1. Washington DC is the capital of the United States (Country: USA)
2. Canberra is the capital of Australia (Country: Australia)
3. Paris is the capital of France (Country: France)
```

### 处理空文档

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 创建一个包含空文档的检索器
empty_retriever = NebiusRetriever(
    embeddings=embeddings,
    docs=[],
    k=2,  # 空文档列表
)

# 使用空文档测试检索器
results = empty_retriever.invoke("What are the capitals of European countries?")
print(f"Number of results: {len(results)}")
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Number of results: 0
```

## 在链中使用

NebiusRetriever 可以无缝地在 LangChain RAG 管道中工作。以下是使用 NebiusRetriever 创建简单 RAG 链的示例：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_nebius import ChatNebius

# 初始化 LLM
llm = ChatNebius(model="meta-llama/Llama-3.3-70B-Instruct-fast")

# 创建提示模板
prompt = ChatPromptTemplate.from_template(
    """
Answer the question based only on the following context:

Context:
{context}

Question: {question}
"""
)


# 格式化文档函数
def format_docs(docs):
    return "\n\n".join(doc.page_content for doc in docs)


# 创建 RAG 链
rag_chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)

# 运行链
answer = rag_chain.invoke("What are three European capitals?")
print(answer)
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Based on the context provided, three European capitals are:

1. Paris
2. Berlin
3. Rome
```

### 创建搜索工具

您可以使用 `NebiusRetrievalTool` 为代理创建工具：

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
from langchain_nebius import NebiusRetrievalTool

# 创建检索工具
tool = NebiusRetrievalTool(
    retriever=retriever,
    name="capital_search",
    description="Search for information about capital cities around the world",
)

# 使用工具
result = tool.invoke({"query": "capitals in Europe", "k": 3})
print("Tool results:")
print(result)
```

```text theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
Tool results:
Document 1:
Paris is the capital of France

Document 2:
Berlin is the capital of Germany

Document 3:
Rome is the capital of Italy
```

## 工作原理

NebiusRetriever 的工作原理如下：

1. 在初始化期间：
   * 它存储提供的文档
   * 它使用提供的 NebiusEmbeddings 为所有文档计算嵌入向量
   * 这些嵌入向量存储在内存中以便快速检索

2. 在检索期间（`invoke` 或 `get_relevant_documents`）：
   * 它使用相同的嵌入模型对查询进行嵌入
   * 它计算查询嵌入向量与所有文档嵌入向量之间的相似度分数
   * 它返回按相似度排序的前 k 个文档

这种方法对于中等规模的文档集合非常高效，因为它避免了对单独向量数据库的需求，同时仍提供高质量的语义搜索。

***

## API 参考

有关 Nebius Token Factory API 的更多详细信息，请访问 [Nebius Token Factory 文档](https://docs.tokenfactory.nebius.com/quickstart)。

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/python/integrations/retrievers/nebius.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>