Qianfan Python SDK

0.4.12.3 · active · verified Thu Apr 16

The Qianfan Python SDK provides a convenient way to interact with Baidu Wenxin Qianfan Large Model Platform. It supports various AI capabilities including chat completion, text completion, embeddings, text-to-image, and more. The library is actively maintained, with frequent releases across Python, Go, and JavaScript, ensuring up-to-date access to Qianfan services.

Common errors

```
qianfan.common.exception.APIErrorCode: ErrorCode=2, ErrorMsg=Authentication failed: The Access Key or Secret Key is invalid.
```
cause The `QIANFAN_AK` or `QIANFAN_SK` environment variables are missing, incorrect, or not loaded, or `ak`/`sk` were not passed during client initialization.

fix Verify that `QIANFAN_AK` and `QIANFAN_SK` environment variables are correctly set and valid, or explicitly pass `ak` and `sk` to the client constructor, e.g., `ChatCompletion(ak='YOUR_AK', sk='YOUR_SK')`.
```
ImportError: cannot import name 'ChatCompletion' from 'qianfan'
```
cause This usually means the `qianfan` package is not installed, or you are running an outdated version that doesn't expose `ChatCompletion` at the top level, or there's a typo in the import.

fix Ensure `qianfan` is installed (`pip install qianfan`) and up-to-date (`pip install --upgrade qianfan`). Verify the import statement for typos, it should be `from qianfan import ChatCompletion`.
```
qianfan.common.exception.APIErrorCode: ErrorCode=17, ErrorMsg=The provided model name is invalid.
```
cause The specified model name is either incorrect, misspelled, not supported by your account, or uses incorrect casing (e.g., 'ernie-bot' instead of 'ERNIE-Bot').

fix Check the official Qianfan documentation for the exact, case-sensitive names of available models. Ensure the model is enabled for your account. For versions >=0.4.12.3, pay close attention to model name casing.
```
TypeError: do() got an unexpected keyword argument 'stream'
```
cause You might be calling a method (e.g., for embeddings or non-streaming completion) that does not support the `stream` parameter, or using an older client version that doesn't support streaming for that specific API.

fix Remove the `stream=...` parameter if the API endpoint does not support streaming (e.g., embedding generation). For chat/completion APIs that do support streaming, ensure your `qianfan` SDK version is up-to-date and the `stream` parameter is used correctly for that specific model.

Warnings

gotcha Authentication requires 'QIANFAN_AK' and 'QIANFAN_SK' environment variables. If these are not set, the SDK client must be initialized by passing `ak` and `sk` keyword arguments directly, otherwise API calls will fail.
Fix: Set `QIANFAN_AK` and `QIANFAN_SK` in your environment, or initialize clients like `ChatCompletion(ak="YOUR_AK", sk="YOUR_SK")`.
breaking As of v0.4.12.3, the SDK removed the forced lowercase conversion of model names. This means you must now use the exact case-sensitive model names as specified in the Qianfan documentation (e.g., 'ERNIE-Bot-4' instead of 'ernie-bot-4').
Fix: Always use the official, case-sensitive model names provided by Qianfan, e.g., `model="ERNIE-Bot-4"`.
gotcha When using streaming (`stream=True`), the `do()` method returns an iterable. You must iterate over the response to receive partial results. Not iterating will result in no output.
Fix: Process streaming responses with a loop: `for chunk in chat_comp.do(..., stream=True): print(chunk.result)`.
gotcha Some error messages from the Qianfan API might be returned in Chinese, which can be challenging for non-Chinese speakers to debug directly. Refer to the official documentation for common error codes.
Fix: Translate error messages or consult the Baidu Qianfan API documentation for known error codes and their English descriptions.

Install

pip install qianfan Install latest version

Imports

ChatCompletion
wrong:
```
from qianfan.chat import ChatCompletion
```
correct:
```
from qianfan import ChatCompletion
```
Top-level import for core client classes is preferred.
Completion
```
from qianfan import Completion
```
Embedding
```
from qianfan import Embedding
```
QfMessages
wrong:
```
from qianfan import Messages
```
correct:
```
from qianfan import QfMessages
```
Use `QfMessages` for defining chat message roles and content, `Messages` might be deprecated or internal in some contexts.

Quickstart

This quickstart demonstrates how to perform a simple chat completion using the `qianfan` SDK. It initializes a `ChatCompletion` client, constructs messages using `QfMessages`, and sends a request to the ERNIE-Bot-4 model. Ensure your `QIANFAN_AK` and `QIANFAN_SK` environment variables are set for authentication.

import os
from qianfan import ChatCompletion, QfMessages

# Set your Baidu Cloud API Key and Secret Key as environment variables
# or pass them directly to the client constructor.
# os.environ["QIANFAN_AK"] = "YOUR_AK"
# os.environ["QIANFAN_SK"] = "YOUR_SK"

ak = os.environ.get("QIANFAN_AK", "")
sk = os.environ.get("QIANFAN_SK", "")

if not ak or not sk:
    print("Please set QIANFAN_AK and QIANFAN_SK environment variables.")
else:
    chat_comp = ChatCompletion(ak=ak, sk=sk)

    messages = [
        QfMessages(role="user", content="Hello, how are you?")
    ]

    try:
        response = chat_comp.do(
            model="ERNIE-Bot-4", # Or another available chat model like 'ERNIE-Bot-turbo'
            messages=messages,
            stream=False
        )

        if response and response.result:
            print(f"Qianfan response: {response.result}")
        else:
            print("No valid response from Qianfan.")

    except Exception as e:
        print(f"An error occurred: {e}")

view raw JSON →