langchain-xai

注意

此软件包参考尚未完全迁移到 v1。

langchain_xai

LangChain 与 xAI 的集成。

ChatXAI

Bases: BaseChatOpenAI

ChatXAI 聊天模型。

请参考 xAI 的文档，了解有关 API 行为和支持参数的更细微的详细信息。

设置

安装 langchain-xai 并设置环境变量 XAI_API_KEY。

pip install -U langchain-xai
export XAI_API_KEY="your-api-key"

关键初始化参数 — completion params: model: 要使用的模型名称。 temperature: 介于 0 和 2 之间的采样温度。较高的值意味着更随机的补全，而较低的值（如 0.2）意味着更专注和确定性的补全。（默认值：1。） max_tokens: 要生成的最大 token 数。请参考您的模型文档，了解其可以生成的最大 token 数。 logprobs: 是否返回 logprobs。

关键初始化参数 — client params: timeout: 请求超时。 max_retries: 最大重试次数。 api_key: xAI API 密钥。如果未传入，将从环境变量 XAI_API_KEY 中读取。

实例化

from langchain_xai import ChatXAI

model = ChatXAI(
    model="grok-4",
    temperature=0,
    max_tokens=None,
    timeout=None,
    max_retries=2,
    # api_key="...",
    # other params...
)

调用

messages = [
    (
        "system",
        "You are a helpful translator. Translate the user sentence to French.",
    ),
    ("human", "I love programming."),
]
model.invoke(messages)

AIMessage(
    content="J'adore la programmation.",
    response_metadata={
        "token_usage": {
            "completion_tokens": 9,
            "prompt_tokens": 32,
            "total_tokens": 41,
        },
        "model_name": "grok-4",
        "system_fingerprint": None,
        "finish_reason": "stop",
        "logprobs": None,
    },
    id="run-168dceca-3b8b-4283-94e3-4c739dbc1525-0",
    usage_metadata={
        "input_tokens": 32,
        "output_tokens": 9,
        "total_tokens": 41,
    },
)

流

for chunk in model.stream(messages):
    print(chunk.text, end="")

content='J' id='run-1bc996b5-293f-4114-96a1-e0f755c05eb9'
content="'" id='run-1bc996b5-293f-4114-96a1-e0f755c05eb9'
content='ad' id='run-1bc996b5-293f-4114-96a1-e0f755c05eb9'
content='ore' id='run-1bc996b5-293f-4114-96a1-e0f755c05eb9'
content=' la' id='run-1bc996b5-293f-4114-96a1-e0f755c05eb9'
content=' programm' id='run-1bc996b5-293f-4114-96a1-e0f755c05eb9'
content='ation' id='run-1bc996b5-293f-4114-96a1-e0f755c05eb9'
content='.' id='run-1bc996b5-293f-4114-96a1-e0f755c05eb9'
content='' response_metadata={'finish_reason': 'stop', 'model_name': 'grok-4'} id='run-1bc996b5-293f-4114-96a1-e0f755c05eb9'

异步

await model.ainvoke(messages)

# stream:
# async for chunk in (await model.astream(messages))

# batch:
# await model.abatch([messages])

AIMessage(
    content="J'adore la programmation.",
    response_metadata={
        "token_usage": {
            "completion_tokens": 9,
            "prompt_tokens": 32,
            "total_tokens": 41,
        },
        "model_name": "grok-4",
        "system_fingerprint": None,
        "finish_reason": "stop",
        "logprobs": None,
    },
    id="run-09371a11-7f72-4c53-8e7c-9de5c238b34c-0",
    usage_metadata={
        "input_tokens": 32,
        "output_tokens": 9,
        "total_tokens": 41,
    },
)

推理

某些 xAI 模型支持推理，这允许模型在响应中提供推理内容。

如果提供，推理内容将返回在 AIMessage 或 AIMessageChunk 的 additional_kwargs 字段下。

如果支持，可以在模型构造函数的 extra_body 参数中指定推理强度 (reasoning effort)，这将控制模型执行的推理量。该值可以是 'low' 或 'high' 之一。

model = ChatXAI(
    model="grok-3-mini",
    extra_body={"reasoning_effort": "high"},
)

注意

截至 2025-07-10，reasoning_content 仅在 Grok 3 模型中返回，例如 Grok 3 Mini。

注意

请注意，在 Grok 4 中，截至 2025-07-10，推理内容并未在 reasoning_content 中公开（除了初始的 'Thinking...' 文本），推理无法被禁用，并且无法指定 reasoning_effort。

工具调用 / 函数调用

from pydantic import BaseModel, Field

model = ChatXAI(model="grok-4")


class GetWeather(BaseModel):
    '''Get the current weather in a given location'''

    location: str = Field(..., description="The city and state, e.g. San Francisco, CA")


class GetPopulation(BaseModel):
    '''Get the current population in a given location'''

    location: str = Field(..., description="The city and state, e.g. San Francisco, CA")


model_with_tools = model.bind_tools([GetWeather, GetPopulation])
ai_msg = model_with_tools.invoke("Which city is bigger: LA or NY?")
ai_msg.tool_calls

[
    {
        "name": "GetPopulation",
        "args": {"location": "NY"},
        "id": "call_m5tstyn2004pre9bfuxvom8x",
        "type": "tool_call",
    },
    {
        "name": "GetPopulation",
        "args": {"location": "LA"},
        "id": "call_0vjgq455gq1av5sp9eb1pw6a",
        "type": "tool_call",
    },
]

注意

对于流式响应，工具/函数调用将在单个数据块中完整返回，而不是在多个数据块中流式传输。

可以通过在模型构造函数的 extra_body 参数中设置 tool_choice 参数来控制工具选择。例如，要禁用工具/函数调用

model = ChatXAI(model="grok-4", extra_body={"tool_choice": "none"})

要强制模型始终调用工具/函数，请将 tool_choice 设置为 'required'

model = ChatXAI(model="grok-4", extra_body={"tool_choice": "required"})

要指定要调用的工具/函数，请将 tool_choice 设置为该工具/函数的名称

from pydantic import BaseModel, Field

model = ChatXAI(
    model="grok-4",
    extra_body={
        "tool_choice": {"type": "function", "function": {"name": "GetWeather"}}
    },
)

class GetWeather(BaseModel):
    \"\"\"Get the current weather in a given location\"\"\"

    location: str = Field(..., description='The city and state, e.g. San Francisco, CA')


class GetPopulation(BaseModel):
    \"\"\"Get the current population in a given location\"\"\"

    location: str = Field(..., description='The city and state, e.g. San Francisco, CA')


model_with_tools = model.bind_tools([GetWeather, GetPopulation])
ai_msg = model_with_tools.invoke(
    "Which city is bigger: LA or NY?",
)
ai_msg.tool_calls

生成的工具调用将是

[
    {
        "name": "GetWeather",
        "args": {"location": "Los Angeles, CA"},
        "id": "call_81668711",
        "type": "tool_call",
    }
]

并行工具调用 / 并行函数调用：默认情况下，并行工具/函数调用是启用的，因此您可以在一个请求/响应周期中处理多个函数调用。当需要两个或更多工具调用时，所有的工具调用请求都将包含在响应体中。

结构化输出

from typing import Optional

from pydantic import BaseModel, Field


class Joke(BaseModel):
    '''Joke to tell user.'''

    setup: str = Field(description="The setup of the joke")
    punchline: str = Field(description="The punchline to the joke")
    rating: int | None = Field(description="How funny the joke is, from 1 to 10")


structured_model = model.with_structured_output(Joke)
structured_model.invoke("Tell me a joke about cats")

Joke(
    setup="Why was the cat sitting on the computer?",
    punchline="To keep an eye on the mouse!",
    rating=7,
)

实时搜索

xAI 支持实时搜索功能，该功能使 Grok 能够利用网络搜索结果来支撑其回答。

from langchain_xai import ChatXAI

model = ChatXAI(
    model="grok-4",
    search_parameters={
        "mode": "auto",
        # Example optional parameters below:
        "max_search_results": 3,
        "from_date": "2025-05-26",
        "to_date": "2025-05-27",
    },
)

model.invoke("Provide me a digest of world news in the last 24 hours.")

注意

引用功能仅在 Grok 3 中可用。

令牌使用情况

ai_msg = model.invoke(messages)
ai_msg.usage_metadata

{"input_tokens": 37, "output_tokens": 6, "total_tokens": 43}

Logprobs

logprobs_model = model.bind(logprobs=True)
messages = [("human", "Say Hello World! Do not return anything else.")]
ai_msg = logprobs_model.invoke(messages)
ai_msg.response_metadata["logprobs"]

{
    "content": None,
    "token_ids": [22557, 3304, 28808, 2],
    "tokens": [" Hello", " World", "!", "</s>"],
    "token_logprobs": [-4.7683716e-06, -5.9604645e-07, 0, -0.057373047],
}

响应元数据

ai_msg = model.invoke(messages)
ai_msg.response_metadata

{
    "token_usage": {
        "completion_tokens": 4,
        "prompt_tokens": 19,
        "total_tokens": 23,
    },
    "model_name": "grok-4",
    "system_fingerprint": None,
    "finish_reason": "stop",
    "logprobs": None,
}

方法	描述
get_lc_namespace	获取 LangChain 对象的命名空间。
is_lc_serializable	返回此模型是否可以被 LangChain 序列化。
validate_environment	验证 API 密钥和 Python 包是否存在于环境中。
with_structured_output	返回与给定模式匹配的格式化输出的模型包装器。

model_name class-attribute instance-attribute

model_name: str = Field(default='grok-4', alias='model')

要使用的模型名称。

xai_api_key class-attribute instance-attribute

xai_api_key: SecretStr | None = Field(
    alias="api_key", default_factory=secret_from_env("XAI_API_KEY", default=None)
)

xAI API 密钥。

如果未提供，则自动从环境变量 XAI_API_KEY 中读取。

xai_api_base class-attribute instance-attribute

xai_api_base: str = Field(default='https://api.x.ai/v1/')

API 请求的基础 URL 路径。

search_parameters class-attribute instance-attribute

search_parameters: dict[str, Any] | None = None

搜索请求的参数。例如：{"mode": "auto"}。

lc_secrets property

lc_secrets: dict[str, str]

构造函数参数名称到密钥 ID 的映射。

例如，{"xai_api_key": "XAI_API_KEY"}

lc_attributes property

lc_attributes: dict[str, Any]

应包含在序列化 kwargs 中的属性名称列表。

这些属性必须被构造函数接受。

get_lc_namespace classmethod

get_lc_namespace() -> list[str]

获取 LangChain 对象的命名空间。

返回	描述
list[str]	["langchain_xai", "chat_models"]

is_lc_serializable classmethod

is_lc_serializable() -> bool

返回此模型是否可以被 LangChain 序列化。

validate_environment

validate_environment() -> Self

验证 API 密钥和 Python 包是否存在于环境中。

with_structured_output

with_structured_output(
    schema: _DictOrPydanticClass | None = None,
    *,
    method: Literal[
        "function_calling", "json_mode", "json_schema"
    ] = "function_calling",
    include_raw: bool = False,
    strict: bool | None = None,
    **kwargs: Any,
) -> Runnable[LanguageModelInput, _DictOrPydantic]

返回与给定模式匹配的格式化输出的模型包装器。

参数	描述
模式	输出模式。可以作为以下形式传入： 一个 OpenAI 函数/工具模式， 一个 JSON Schema， 一个 TypedDict 类， 或一个 Pydantic 类。 如果 schema 是一个 Pydantic 类，那么模型输出将是该类的 Pydantic 实例，并且模型生成的字段将由 Pydantic 类进行验证。否则，模型输出将是一个字典，并且不会被验证。 有关在指定 Pydantic 或 TypedDict 类时如何正确指定模式字段的类型和描述的更多信息，请参阅 langchain_core.utils.function_calling.convert_to_openai_tool。 TYPE: _DictOrPydanticClass | None DEFAULT: None
method	用于引导模型生成的方法，可选值之一： 'function_calling': 使用 xAI 的工具调用功能。 'json_schema': 使用 xAI 的结构化输出功能。 'json_mode': 使用 xAI 的 JSON 模式功能。 类型： Literal['function_calling', 'json_mode', 'json_schema'] 默认值： 'function_calling'
包含原始数据	如果为 False，则仅返回解析后的结构化输出。如果在模型输出解析期间发生错误，它将被引发。如果为 True，则将返回原始模型响应（一个 BaseMessage）和解析后的模型响应。如果在输出解析期间发生错误，它将被捕获并一并返回。 最终输出总是一个带有键 'raw'、'parsed' 和 'parsing_error' 的 dict。 类型： bool 默认值： False
strict	`True`：模型输出保证与模式完全匹配。输入模式也将根据支持的模式进行验证。 False：不会验证输入模式，也不会验证模型输出。 None：strict 参数不会传递给模型。 类型： bool | None 默认值： None
kwargs	不支持额外的关键字参数。 类型： Any 默认值： {}

返回	描述
Runnable[LanguageModelInput, _DictOrPydantic]	一个接受与 langchain_core.language_models.chat.BaseChatModel 相同输入的 Runnable。如果 include_raw 为 False 且 schema 是一个 Pydantic 类，则 Runnable 输出一个 schema 的实例（即一个 Pydantic 对象）。否则，如果 include_raw 为 False，则 Runnable 输出一个 dict。 如果 include_raw 为 True，则 Runnable 输出一个带有以下键的 dict 'raw': BaseMessage 'parsed': 如果出现解析错误则为 None，否则类型取决于上面描述的 schema。 'parsing_error': BaseException | None