Add comprehensive documentation and templates for LangChain skill development
- Introduced a new reference document for streaming output issues, detailing the differences between streaming APIs and providing solutions for common problems. - Created a structured output issues reference, outlining the use of `with_structured_output`, `response_format`, and schema enforcement strategies. - Added a user query convention guide to standardize structured questions for skill authors, including block types for queries and data gathering. - Implemented a template for a chat model, encapsulating API key management, request payload construction, and response handling. - Established a symlink for the LangChain dev guide in the Claude skills directory for easier access. - Initialized a skills lock file to manage dependencies and versions for the LangChain dev guide.
This commit is contained in:
yuxuanhui
@@ -0,0 +1,99 @@
|
||||
# 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.
|
||||
|
||||
<!-- gather
|
||||
prompt: "Confirm the following details for the model integration:"
|
||||
fields:
|
||||
- name: model_name
|
||||
question: "Model name (lowercase, used for directory and class names)"
|
||||
example: "qwen"
|
||||
required: true
|
||||
- name: api_base
|
||||
question: "API base URL (OpenAI-compatible endpoint)"
|
||||
example: "https://dashscope.aliyuncs.com/compatible-mode/v1"
|
||||
required: true
|
||||
- name: api_key_env
|
||||
question: "API key environment variable name"
|
||||
example: "QWEN_API_KEY"
|
||||
required: true
|
||||
fallback: "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](../../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:
|
||||
|
||||
```bash
|
||||
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](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](integration-tests.md) for fixes.
|
||||
Reference in New Issue
Block a user