What causes "向量生成失败: {str(e)}" in datawhalechina/hello-agents?

Check the wrapped message: 401 → fix api_key, 404/model_not_found → fix embedding_model in config.vector_db, 429 → add backoff/retry

datawhalechina/hello-agents · error · AgentException

向量生成失败: {str(e)}

Error message

向量生成失败: {str(e)}

What it means

An AgentException raised by EmbeddingGenerator.generate_embedding() in utils/embedding.py when the OpenAI embeddings call fails. The try wraps the API request and response extraction (response.data[0].embedding); typical causes are wrong model name, auth errors, network failures, rate limits, or empty text issues slipping past the early return. The original cause survives only as its string form, losing the exception type and status code.

Source

Thrown at Co-creation-projects/Apricity-InnocoreAI/utils/embedding.py:65

            cleaned_text = self._clean_text(text)
            
            # 调用OpenAI API
            response = await self.client.embeddings.create(
                model=self.embedding_model,
                input=cleaned_text
            )
            
            embedding = response.data[0].embedding
            
            # 缓存结果
            if use_cache:
                cache_key = self._get_cache_key(text)
                self.cache[cache_key] = embedding
            
            return embedding
            
        except Exception as e:
            raise AgentException(f"向量生成失败: {str(e)}")
    
    async def generate_batch_embeddings(self, texts: List[str], 
                                       batch_size: int = 10) -> List[List[float]]:
        """批量生成向量"""
        embeddings = []
        
        for i in range(0, len(texts), batch_size):
            batch = texts[i:i + batch_size]
            
            try:
                # 批量调用API
                cleaned_texts = [self._clean_text(text) for text in batch]
                
                response = await self.client.embeddings.create(
                    model=self.embedding_model,
                    input=cleaned_texts
                )

View on GitHub (pinned to 606a07d341)

Solutions

Check the wrapped message: 401 → fix api_key, 404/model_not_found → fix embedding_model in config.vector_db, 429 → add backoff/retry
Verify the endpoint actually serves the configured model with a one-off curl to {base_url}/models
Add retry with exponential backoff around the call for 429/5xx (the openai SDK honors max_retries on the client)
Preserve the original exception: raise AgentException(...) from e so tracebacks show the root cause
Trim/validate text before the call so whitespace-only input takes the zero-vector path

Example fix

# before
except Exception as e:
    raise AgentException(f"向量生成失败: {str(e)}")

# after
except Exception as e:
    raise AgentException(f"向量生成失败: {str(e)}") from e
# plus, on the client:
self.client = AsyncOpenAI(api_key=..., base_url=..., max_retries=3)

Defensive patterns

Strategy: retry

Validate before calling

assert embedder.client is not None, 'call initialize() before generate_embedding()'
assert isinstance(text, str) and text.strip(), 'empty/whitespace text yields zero vectors'
# optionally verify model availability:
models = [m.id for m in await embedder.client.models.list()]
assert embedder.embedding_model in models

Try / catch

for attempt in range(3):
    try:
        return await embedder.generate_embedding(text)
    except AgentException as e:
        msg = str(e)
        if '429' in msg or 'timeout' in msg or 'connection' in msg.lower():
            await asyncio.sleep(2 ** attempt); continue
        raise  # auth/model errors are not retried

Prevention

Configure the openai client with max_retries and sane timeouts for embedding calls
Verify embedding_model against the provider's /models endpoint at startup
Cache embeddings (the class already does) to reduce quota pressure during bulk indexing
Raise with 'from e' in wrappers to keep the root cause inspectable

When it happens

Trigger: Calling generate_embedding(text) with config.vector_db.embedding_model set to a model the endpoint does not serve (e.g. 'text-embedding-3-small' against a gateway exposing only 'bge-large'); invalid/expired api_key (401); rate limit (429); connectivity problems to base_url; or an API response with empty data raising IndexError. Empty string text returns a zero vector before the call, so whitespace-only or None inputs reaching the API can also error.

Common situations: Switching embedding providers without updating the model name in config; hitting OpenAI rate limits during bulk indexing (the batch path calls this repeatedly); expired keys; local embedding server down; mixing the chat-LLM credential with an embedding-only credential.

Related errors

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/88e2c8e484ec4301. Report an issue: GitHub.