worldquant-alpha-system/.agents/skills/langchain-dev-guide/reference/cn-models

CN Model Integration Guide

Help developers write LangChain integration classes for a specified Chinese model (e.g., Qwen, GLM, DeepSeek, Moonshot) using the OpenAI-compatible interface.

Caution

Never read, write, or access user configuration files such as .env, .env.local, credentials.json, or any other files that may contain secrets or sensitive information. API Keys and other credentials must always be filled in by the user themselves — do not peek into or modify these files under any circumstances.

Step 1: Gather Information

Confirm the following details with the user. If the user does not explicitly provide any of these, use reasonable defaults from the provider's documentation.

1. Model Name — lowercase, e.g., qwen, glm, deepseek. Used for directory names, class names, and _llm_type.
2. API Base URL — the model's OpenAI-compatible endpoint URL.
3. API Key Environment Variable Name — e.g., QWEN_API_KEY.

Additionally, inspect the project directory structure to determine the Python package manager (uv.lock → uv, poetry.lock → poetry, requirements.txt → pip, etc.).

Step 2: Create Directory and Files

1. Create a top-level directory <models_dir>/.
2. Create a model subdirectory <models_dir>/<model_name>/ with model_name in lowercase.
3. Keep the top-level <models_dir>/__init__.py empty.

<models_dir>/
├── __init__.py                   # empty
├── <model_name>/
│   ├── __init__.py
│   └── chat_model.py
└── ...

Step 3: Check if DeepSeek

If the model is DeepSeek, install langchain-deepseek and use ChatDeepSeek directly. Skip all subsequent steps.

If the model is another provider, continue with the steps below.

Step 4: Copy the Template

1. Check whether langchain-openai is installed; install it if not.
2. Copy the template from ../../template/chat_model.py into the target subdirectory.
3. Create __init__.py: from .chat_model import <CHAT_CLASS_NAME>

Step 5: Replace Placeholders

Use grep to list all placeholders, then replace each one with the actual value:

Placeholder	Description	Example (Qwen)
ChatModel	Class name	ChatQwen
PROVIDER_API_KEY	API Key env var name	QWEN_API_KEY
PROVIDER_API_BASE	API Base env var name	QWEN_API_BASE
PROVIDER_API_BASE_URL	Default API URL	https://dashscope.aliyuncs.com/compatible-mode/v1
chat-provider	Model identifier for _llm_type	chat-qwen
provider-name	Value for response_metadata["model_provider"]	dashscope
Provider	Provider display name for error messages	Qwen

Each placeholder is a standalone, complete token — simply do a global find-and-replace. Apply replacements in both chat_model.py and __init__.py.

Step 6: Configure Model Profile (Optional)

Use langchain-model-profiles to download profile information for the model provider. <provider_name> is the provider name; try a few likely candidates.

1. Check whether langchain-model-profiles is installed; install it if not.
2. Run the download command:

langchain-profiles refresh --provider <provider_name> --data-dir ./<models_dir>/<model_name>/data

On success, a data/_profiles.py file is generated under the model directory, which is used by _get_default_model_profile in the template. If you cannot find the corresponding provider after several attempts, skip this step.

Step 7: Write Integration Tests

After the model class is complete, you must write integration tests. See the detailed guide at integration-tests.md.

Important

Before running integration tests, you must remind the user to edit the .env file themselves and fill in the required API Key and other environment variables.

When running tests, you will likely encounter common setup issues (package not importable, async test mode, etc.). Refer to the "Common Issues" section at the end of integration-tests.md for fixes.